From d4f3d3d83d1befdc7bb4059c78dbc20ae0d340e6 Mon Sep 17 00:00:00 2001 From: Pete Vander Giessen Date: Tue, 29 Jan 2019 10:30:41 -0500 Subject: [PATCH] Added CONTRIBUTING.md. Also added a link to launchpad in the README. --- CONTRIBUTING.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++++ 2 files changed, 62 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6648b34 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contributing + +## Building Microstack + +Currently, you must build microstack on a machine running Ubuntu 16.04 Xenial. A goal of the project is to expand this to other environments, but for now, there are some Debian packages specific to Xenial required in snapcraft.yaml. + +To build microstack, do the following: + +``` +export PATH=/snap/bin:$PATH +sudo snap install --classic snapcraft +git clone git@github.com:CanonicalLtd/microstack.git +cd microstack +snapcraft +``` + +Optionally, if you want to keep the system clean of dependencies, you can install lxd and do a cleanbuild (note that the apt packaged version of lxd in Xenial won't work -- you want to use the snap). + +``` +sudo snap install --classic lxd +sudo usermod -aG lxd +newgrp lxd +lxd init # Going with the defaults is fine +``` + +Then replace `snapcraft` above with `snapcraft cleanbuild` + +## How the Code is Structured + +Microstack is a Snap, which means that, after it has been built, it contains all the code and dependencies that it needs, destined to be mounted in a read only file system on a host. + +Before contributing, you probably want to read the general Snap Documentation here: https://docs.snapcraft.io/snap-documentation/3781 + +There are several important files and directories in microstack, some of which are like those in other snaps, some of which are unique to microstack: + +### `./snapcraft.yaml` + +This is the core of the snap. You'll want to start here when it comes to adding code. And you may not need to leave this file at all. + +### `./snap-overlay` + +Any files you add to snap-overlay will get written to the corresponding place in the file hierarchy under `/snap/microstack/common/`. Drop files in here if you want to insert a file or directory that does not come bundled by default with the Openstack source tarballs. + +### `./snap-overlay/snap-openstack.yaml` + +This is a yaml file unique to Snaps created by the Openstack team at Canonical. It creates a command called `snap-openstack`, which wraps Openstack daemons and scripts. + +Documentation for this helper lives here: https://github.com/openstack/snap.openstack + +It's installed by the openstack-projects part. + +If you're adding an Openstack component to the snap, you may find it useful to take a look at the parts and apps that take advantage of snap-openstack, and add your own section to `snap-openstack.yaml`. + +### Filing Bug and Submitting Pull Requests + +We track bugs and features on launchpad, at https://bugs.launchpad.net/microstack + +To submit a bugfix or feature, please fork the github repo, and create a pull request against it. The microstackers team will see it and review your code. diff --git a/README.md b/README.md index 87e0646..f6cb223 100644 --- a/README.md +++ b/README.md @@ -101,3 +101,7 @@ and re-enabled latest using: ``` sudo snap enable microstack ``` + +## Raising a Bug + +Please report bugs to the microstack project on launchpad: https://bugs.launchpad.net/microstack