x
/
microstack
Code Issues Proposed changes
Browse Source

Updated "Building MicroStack" section of CONTRIBUTING.md 

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
changes/02/693902/3
Pete Vander Giessen 2 months ago
parent
2f5847d6ad
commit
e0fd42e55c
1 changed files with 62 additions and 33 deletions
Split View Show Diff Stats
  1. +62
    -33
      CONTRIBUTING.md

+ 62
- 33
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

Write Preview
Loading…
Cancel
Save