Browse Source

Developer Docs

These docs describe how to set up a development environment with
Mixmatch.

Change-Id: I53e34babb883facf1d3a9390a2366d4ad9c68e28
Kristi Nikolla 1 year ago
parent
commit
dfd5fff51d
3 changed files with 104 additions and 6 deletions
  1. 0
    4
      doc/source/contributing.rst
  2. 14
    2
      doc/source/index.rst
  3. 90
    0
      doc/source/reference.rst

+ 0
- 4
doc/source/contributing.rst View File

@@ -1,4 +0,0 @@
1
-============
2
-Contributing
3
-============
4
-.. include:: ../../CONTRIBUTING.rst

+ 14
- 2
doc/source/index.rst View File

@@ -8,6 +8,9 @@ Welcome to mixmatch's documentation!
8 8
 
9 9
 Contents:
10 10
 
11
+Operators Guide
12
+---------------
13
+
11 14
 ..  toctree::
12 15
     :maxdepth: 2
13 16
 
@@ -16,14 +19,23 @@ Contents:
16 19
     installation
17 20
     identity
18 21
     volumes
19
-    contributing
22
+
23
+* `Release Notes <https://mixmatch.readthedocs.org/projects/releasenotes>`_
24
+
25
+Contributors Guide
26
+------------------
27
+
28
+..  toctree::
29
+    :maxdepth: 2
30
+   
31
+   reference
20 32
 
21 33
 ..  toctree::
22 34
     :maxdepth: 1
23 35
 
24 36
     specs
25 37
 
26
-* `Release Notes <https://mixmatch.readthedocs.org/projects/releasenotes>`_
38
+
27 39
 
28 40
 Indices and tables
29 41
 ==================

+ 90
- 0
doc/source/reference.rst View File

@@ -0,0 +1,90 @@
1
+===================
2
+Developer Reference
3
+===================
4
+
5
+The Mixmatch project is generously hosted by the OpenStack infrastructure.
6
+While the project is funded and developed primarily by the Massachusetts Open
7
+Cloud, we are always welcoming to new contributors.
8
+
9
+Contributing to OpenStack
10
+=========================
11
+
12
+.. include:: ../../CONTRIBUTING.rst
13
+
14
+Setting up a development environment
15
+====================================
16
+
17
+Devstack is the mechanism of choice for setting up a development environment.
18
+For the latest branch we recommend a virtual machine running Ubuntu 16.04, with
19
+more than 4GB of RAM and 40GB of space.
20
+
21
+Clone Devstack from git (#1) and copy the sample configuration file from the
22
+samples 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
+
30
+Devstack is extensible and allows plugins for the installation and
31
+configuration of different additional components depending on need. Mixmatch
32
+provides one such Devstack plugin, so let's go ahead an enable it by adding
33
+the following line at the end of `local.conf`. ::
34
+
35
+    enable_plugin mixmatch git://git.openstack.org/openstack/mixmatch
36
+    REGISTER_MIXMATCH=true
37
+
38
+Finally, run `stack.sh`. (We recommend doing so inside a screen in case of
39
+connectivity issues.) This should take around 20-30 minutes and is a good time
40
+to brew some coffee. ::
41
+
42
+    ./stack.sh
43
+
44
+Running the tests
45
+=================
46
+
47
+There are two types of tests. Unit tests and functional tests. These are run
48
+automatically on every proposed change.
49
+
50
+Unit tests
51
+----------
52
+
53
+Unit tests do not require setting up a development environment and can be
54
+simply run through `tox`. `tox` can be installed through pip (#1) or from the
55
+system 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
62
+selected by running `tox -e <environment>`. Valid environment choices are
63
+`py27`, `py35`, and `pep8`. For example, to run the unit tests in the
64
+Python 2.7 environment: ::
65
+
66
+    tox -e py27
67
+
68
+The `pep8` environment will not run the unit tests, but will check the code
69
+for conformance to the PEP8 coding guidelines for Python.
70
+
71
+Passing the checks for all the above three environments is a hard requirement
72
+for the approval of proposed changes.
73
+
74
+Functional tests
75
+----------------
76
+
77
+While unit tests do not require a development environment, functional tests do.
78
+See above for how to set up one.
79
+
80
+Functional testing is done through tempest. It exercises the proxying
81
+functionality by running all the API tests for the Compute, Volume, and Image
82
+services. Additionally it runs all the scenario tests which simulate a
83
+more realistic workload. We maintain a blacklist file in
84
+`mixmatch/tests/functioanl/tempest_blacklist.txt` for individual tests which
85
+fail for known reasons. To run the functional tests, change into the tempest
86
+directory (#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

Loading…
Cancel
Save