1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
===============================
Developing with OpenStackClient
===============================
Communication
-------------
Meetings
=========
The OpenStackClient team meets regularly on every Thursday. For details
please refer to the `wiki`_.
.. _`wiki`: https://wiki.openstack.org/wiki/Meetings/OpenStackClient
Testing
-------
Using ``tox``
=============
Before running tests, you should have ``tox`` installed and available in your
environment:
.. code-block:: bash
$ pip install tox
To execute the full suite of tests maintained within OpenStackClient, run:
.. code-block:: bash
$ tox
.. NOTE::
The first time you run ``tox``, it will take additional time to build
virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild
your virtualenv in a similar manner.
To run tests for one or more specific test environments (for example, the most
common configuration of Python 2.7 and PEP-8), list the environments with the
``-e`` option, separated by spaces:
.. code-block:: bash
$ tox -e py27,pep8
See ``tox.ini`` for the full list of available test environments.
Running functional tests
========================
OpenStackClient also maintains a set of functional tests that are optimally
designed to be run against OpenStack's gate. Optionally, a developer may
choose to run these tests against any OpenStack deployment, however depending
on the services available, results will vary.
To run the entire suite of functional tests:
.. code-block:: bash
$ tox -e functional
To run a specific functional test:
.. code-block:: bash
$ tox -e functional -- --regex functional.tests.compute.v2.test_server
Running with PDB
================
Using PDB breakpoints with ``tox`` and ``testr`` normally doesn't work since
the tests fail with a `BdbQuit` exception rather than stopping at the
breakpoint.
To run with PDB breakpoints during testing, use the `debug` ``tox`` environment
rather than ``py27``. Here's an example, passing the name of a test since
you'll normally only want to run the test that hits your breakpoint:
.. code-block:: bash
$ tox -e debug opentackclient.tests.identity.v3.test_group
For reference, the `debug` ``tox`` environment implements the instructions
here: https://wiki.openstack.org/wiki/Testr#Debugging_.28pdb.29_Tests
Building the Documentation
--------------------------
The documentation is generated with Sphinx using the ``tox`` command. To
create HTML docs, run the following:
.. code-block:: bash
$ tox -e docs
The resultant HTML will be the ``doc/build/html`` directory.
Release Notes
-------------
The release notes for a patch should be included in the patch. See the
`Project Team Guide`_ for more information on using reno in OpenStack.
.. _`Project Team Guide`: http://docs.openstack.org/project-team-guide/release-management.html#managing-release-notes
If any of the following applies to the patch, a release note is required:
* The deployer needs to take an action when upgrading
* The plugin interface changes
* A new feature is implemented
* A command or option is removed
* Current behavior is changed
* A security bug is fixed
Reno is used to generate release notes. Please read the docs for details. In summary, use
.. code-block:: bash
$ tox -e venv -- reno new <bug-,bp-,whatever>
Then edit the sample file that was created and push it with your change.
To see the results:
.. code-block:: bash
$ git commit # Commit the change because reno scans git log.
$ tox -e releasenotes
Then look at the generated release notes files in releasenotes/build/html in your favorite browser.
Testing new code
----------------
If a developer wants to test new code (feature, command or option) that
they have written, OpenStackClient may be installed from source by running
the following commands in the base directory of the project:
.. code-block:: bash
$ python setup.py develop
or
.. code-block:: bash
$ pip install -e .
|
