x/microstack
Code Issues Proposed changes

Updated "Building MicroStack" section of CONTRIBUTING.md

Browse Source 
Now reflects current build process, and has correct url to source code.

Also changed references to "microstack" and "Microstack" to
"MicroStack".

Change-Id: I60f6a28c3e47ed785692e59c0de79e298e437900
Closes-Bug: 1846979
This commit is contained in:
Pete Vander Giessen 2019-11-12 18:37:08 +00:00
parent 2f5847d6ad
commit e0fd42e55c
1 changed files with 62 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
CONTRIBUTING.md
View File

@ -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 <your username>
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