summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKristi Nikolla <knikolla@bu.edu>2017-06-23 17:03:15 +0000
committerKristi Nikolla <knikolla@bu.edu>2017-09-06 15:26:23 -0400
commitdfd5fff51db628817d09e59f8eb24d8065eb3505 (patch)
treed0de102b1a4579886a2c484f0ab8ce43f1db3a61
parent1d63e7b707c10cfec27ed29f08c3f0ec4d0f44a4 (diff)
Developer Docs
These docs describe how to set up a development environment with Mixmatch. Change-Id: I53e34babb883facf1d3a9390a2366d4ad9c68e28
Notes
Notes (review): Code-Review+2: Kristi Nikolla <knikolla@bu.edu> Workflow+1: Kristi Nikolla <knikolla@bu.edu> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Thu, 07 Sep 2017 14:59:35 +0000 Reviewed-on: https://review.openstack.org/480523 Project: openstack/mixmatch Branch: refs/heads/master
-rw-r--r--doc/source/contributing.rst4
-rw-r--r--doc/source/index.rst16
-rw-r--r--doc/source/reference.rst90
3 files changed, 104 insertions, 6 deletions
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
deleted file mode 100644
index 1728a61..0000000
--- a/doc/source/contributing.rst
+++ /dev/null
@@ -1,4 +0,0 @@
1============
2Contributing
3============
4.. include:: ../../CONTRIBUTING.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 11480f2..ddd0c47 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -8,6 +8,9 @@ Welcome to mixmatch's documentation!
8 8
9Contents: 9Contents:
10 10
11Operators Guide
12---------------
13
11.. toctree:: 14.. toctree::
12 :maxdepth: 2 15 :maxdepth: 2
13 16
@@ -16,14 +19,23 @@ Contents:
16 installation 19 installation
17 identity 20 identity
18 volumes 21 volumes
19 contributing 22
23* `Release Notes <https://mixmatch.readthedocs.org/projects/releasenotes>`_
24
25Contributors Guide
26------------------
27
28.. toctree::
29 :maxdepth: 2
30
31 reference
20 32
21.. toctree:: 33.. toctree::
22 :maxdepth: 1 34 :maxdepth: 1
23 35
24 specs 36 specs
25 37
26* `Release Notes <https://mixmatch.readthedocs.org/projects/releasenotes>`_ 38
27 39
28Indices and tables 40Indices and tables
29================== 41==================
diff --git a/doc/source/reference.rst b/doc/source/reference.rst
new file mode 100644
index 0000000..32aa9de
--- /dev/null
+++ b/doc/source/reference.rst
@@ -0,0 +1,90 @@
1===================
2Developer Reference
3===================
4
5The Mixmatch project is generously hosted by the OpenStack infrastructure.
6While the project is funded and developed primarily by the Massachusetts Open
7Cloud, we are always welcoming to new contributors.
8
9Contributing to OpenStack
10=========================
11
12.. include:: ../../CONTRIBUTING.rst
13
14Setting up a development environment
15====================================
16
17Devstack is the mechanism of choice for setting up a development environment.
18For the latest branch we recommend a virtual machine running Ubuntu 16.04, with
19more than 4GB of RAM and 40GB of space.
20
21Clone Devstack from git (#1) and copy the sample configuration file from the
22samples folder to the root folder (#2). Next, open the newly copied
23`local.conf` file with your editor of choice (in our case `vi` #3).::
24
25 git clone git://git.openstack.org/openstack-dev/devstack #1
26 cd devstack
27 cp samples/local.conf . #2
28 vi local.conf #3
29
30Devstack is extensible and allows plugins for the installation and
31configuration of different additional components depending on need. Mixmatch
32provides one such Devstack plugin, so let's go ahead an enable it by adding
33the following line at the end of `local.conf`. ::
34
35 enable_plugin mixmatch git://git.openstack.org/openstack/mixmatch
36 REGISTER_MIXMATCH=true
37
38Finally, run `stack.sh`. (We recommend doing so inside a screen in case of
39connectivity issues.) This should take around 20-30 minutes and is a good time
40to brew some coffee. ::
41
42 ./stack.sh
43
44Running the tests
45=================
46
47There are two types of tests. Unit tests and functional tests. These are run
48automatically on every proposed change.
49
50Unit tests
51----------
52
53Unit tests do not require setting up a development environment and can be
54simply run through `tox`. `tox` can be installed through pip (#1) or from the
55system packages (#2, #3). ::
56
57 sudo pip install tox #1
58 sudo apt install python-tox #2
59 sudo yum install python-tox #3
60
61`tox` supports multiple testing environments, and a specific one can be
62selected by running `tox -e <environment>`. Valid environment choices are
63`py27`, `py35`, and `pep8`. For example, to run the unit tests in the
64Python 2.7 environment: ::
65
66 tox -e py27
67
68The `pep8` environment will not run the unit tests, but will check the code
69for conformance to the PEP8 coding guidelines for Python.
70
71Passing the checks for all the above three environments is a hard requirement
72for the approval of proposed changes.
73
74Functional tests
75----------------
76
77While unit tests do not require a development environment, functional tests do.
78See above for how to set up one.
79
80Functional testing is done through tempest. It exercises the proxying
81functionality by running all the API tests for the Compute, Volume, and Image
82services. Additionally it runs all the scenario tests which simulate a
83more realistic workload. We maintain a blacklist file in
84`mixmatch/tests/functioanl/tempest_blacklist.txt` for individual tests which
85fail for known reasons. To run the functional tests, change into the tempest
86directory (#1) and run #2: ::
87
88 cd /opt/stack/tempest #1
89 ostestr -r '(^tempest.api.compute|^tempest.api.image|^tempest.api.volume|^tempest.scenario)' \
90 --blacklist-file <MIXMATCH_DIR>/mixmatch/mixmatch/tests/functional/tempest_blacklist.txt #2 \ No newline at end of file