diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6648b34..580a14e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,58 +1,87 @@ # Contributing -## Building Microstack +## 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. +MicroStack builds are tested on an Ubuntu 18.04 LTS machine with 16G +of RAM, two cpu cores, and 50G of free disk space. You should be able +to build MicroStack on any machine matching those minimum specs, as +long as it is capable of running bash and snapd. If you run into any +snags doing so, please file bugs at +https://bugs.launchpad.net/microstack -To build microstack, do the following: +To build MicroStack on a capable machine, run: -``` -export PATH=/snap/bin:$PATH -sudo snap install --classic snapcraft -git clone git@github.com:CanonicalLtd/microstack.git -cd microstack -snapcraft -``` + git clone https://opendev.org/x/microstack.git + cd microstack + tox -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). +This will run tools/multipass_build.sh, which installs some +dependencies on your system, and then run some tests. If you want to +have more control over the build process and installed dependencies, +replace the tox line with: -``` -sudo snap install --classic lxd -sudo usermod -aG lxd -newgrp lxd -lxd init # Going with the defaults is fine -``` + snapcraft -Then replace `snapcraft` above with `snapcraft cleanbuild` +or -## How the Code is Structured + snapcraft --use-lxd -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. +(You may have to install snapcraft and lxd or multipass on your system +first if you go this route -- inspect tools/multipass_build.sh and +tools/lxd_build.sh for tips.) -Before contributing, you probably want to read the general Snap Documentation here: https://docs.snapcraft.io/snap-documentation/3781 +## How the code is structured -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: +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. -### `./snapcraft.yaml` +Before contributing, you probably want to read the general Snap +Documentation here: https://docs.snapcraft.io/snap-documentation/3781 -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. +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: -### `./snap-overlay` +### The Snapcraft yaml -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. + ./snapcraft.yaml -### `./snap-overlay/snap-openstack.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. -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. +### Snap overlay -Documentation for this helper lives here: https://github.com/openstack/snap.openstack + ./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-openstack yaml + + ./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`. +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 +### Filing bugs and submitting pull requests -We track bugs and features on launchpad, at https://bugs.launchpad.net/microstack +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. +To submit a bugfix or feature, please create a Merge Proposal against +the OpenDev repository. See the OpenStack Developer's Guide for more +detail: https://docs.openstack.org/infra/manual/developers.html