« back to all changes in this revision
Viewing changes to doc/source/contribute.rst
- browse files at revision 2675
- compare with another revision
- compare with revision 2675
- download diff
- download tarball
- view history from revision 2675
- Committer: Gerrit Code Review
- Author(s): Jenkins
- Date: 2017-01-10 22:51:59 UTC
- mfrom: (2671.1.1)
- Revision ID: git-v1:15423f7a5c6158ecacc7c4e08c8cceafa8ace7e5
Merge "[docs][6] Re-design docs to cover all user-groups"
- files added:
- CONTRIBUTING.rst
- doc/source/project_info
- doc/source/project_info/release_notes
- files removed:
- doc/source/project_info.rst
- doc/source/release_notes
- files modified:
- doc/feature_request/README.rst
added
removed
doc/source/contribute.rst
21
21
Where to begin
22
22
--------------
23
23
24
Please take a look `our Roadmap <https://docs.google.com/a/mirantis.com/spreadsheets/d/16DXpfbqvlzMFaqaXAcJsBzzpowb_XpymaK2aFY2gA2g/edit#gid=0>`_ to get information about our current work directions.
25
26
In case you have questions or want to share your ideas, be sure to contact us at the ``#openstack-rally`` IRC channel on **irc.freenode.net**.
27
28
If you are going to contribute to Rally, you will probably need to grasp a better understanding of several main design concepts used throughout our project (such as **benchmark scenarios**, **contexts** etc.). To do so, please read :ref:`this article <main_concepts>`.
24
Please take a look `our Roadmap`_ to get information about our current work
25
directions.
26
27
In case you have questions or want to share your ideas, be sure to contact us
28
either at `Rally-dev/Lobby`_ channel on **Gitter** messenger (or, less
29
preferably, at the ``#openstack-rally`` IRC channel on **irc.freenode.net**).
30
31
If you are going to contribute to Rally, you will probably need to grasp a
32
better understanding of several main design concepts used throughout our
33
project (such as **benchmark scenarios**, **contexts** etc.). To do so, please
34
read :ref:`this article <main_concepts>`.
29
35
30
36
31
37
How to contribute
32
38
-----------------
33
39
34
1. You need a `Launchpad <https://launchpad.net/>`_ account and need to be joined to the `OpenStack team <https://launchpad.net/openstack>`_. You can also join the `Rally team <https://launchpad.net/rally>`_ if you want to. Make sure Launchpad has your SSH key, Gerrit (the code review system) uses this.
40
1. You need a `Launchpad`_ account and need to be joined to the
41
`OpenStack team`_. You can also join the `Rally team`_ if you want to. Make
42
sure Launchpad has your SSH key, Gerrit (the code review system) uses this.
35
43
36
2. Sign the CLA as outlined in the `account setup <http://docs.openstack.org/infra/manual/developers.html#development-workflow>`_ section of the developer guide.
44
2. Sign the CLA as outlined in the `account setup`_ section of the developer guide.
37
45
38
46
3. Tell git your details:
39
47
42
50
git config --global user.name "Firstname Lastname"
43
51
git config --global user.email "your_email@youremail.com"
44
52
45
4. Install git-review. This tool takes a lot of the pain out of remembering commands to push code up to Gerrit for review and to pull it back down to edit it. It is installed using:
53
4. Install git-review. This tool takes a lot of the pain out of remembering
54
commands to push code up to Gerrit for review and to pull it back down to edit
55
it. It is installed using:
46
56
47
57
.. code-block:: bash
48
58
49
59
pip install git-review
50
60
51
Several Linux distributions (notably Fedora 16 and Ubuntu 12.04) are also starting to include git-review in their repositories so it can also be installed using the standard package manager.
61
Several Linux distributions (notably Fedora 16 and Ubuntu 12.04) are also
62
starting to include git-review in their repositories so it can also be
63
installed using the standard package manager.
52
64
53
65
5. Grab the Rally repository:
54
66
64
76
65
77
7. Start coding
66
78
67
8. Run the test suite locally to make sure nothing broke, e.g. (this will run py34/py27/pep8 tests):
79
8. Run the test suite locally to make sure nothing broke, e.g. (this will run
80
py34/py27/pep8 tests):
68
81
69
82
.. code-block:: bash
70
83
72
85
73
86
**(NOTE: you should have installed tox<=1.6.1)**
74
87
75
If you extend Rally with new functionality, make sure you have also provided unit and/or functional tests for it.
88
If you extend Rally with new functionality, make sure you have also provided
89
unit and/or functional tests for it.
76
90
77
91
9. Commit your work using:
78
92
81
95
git commit -a
82
96
83
97
84
Make sure you have supplied your commit with a neat commit message, containing a link to the corresponding blueprint / bug, if appropriate.
98
Make sure you have supplied your commit with a neat commit message, containing
99
a link to the corresponding blueprint / bug, if appropriate.
85
100
86
101
10. Push the commit up for code review using:
87
102
89
104
90
105
git review -R
91
106
92
That is the awesome tool we installed earlier that does a lot of hard work for you.
107
That is the awesome tool we installed earlier that does a lot of hard work for
108
you.
93
109
94
11. Watch your email or `review site <http://review.openstack.org/>`_, it will automatically send your code for a battery of tests on our `Jenkins setup <http://jenkins.openstack.org/>`_ and the core team for the project will review your code. If there are any changes that should be made they will let you know.
110
11. Watch your email or `review site`_, it will automatically send your code
111
for a battery of tests on our `Jenkins setup`_ and the core team for the
112
project will review your code. If there are any changes that should be made
113
they will let you know.
95
114
96
115
12. When all is good the review site will automatically merge your code.
97
116
98
117
99
(This tutorial is based on: http://www.linuxjedi.co.uk/2012/03/real-way-to-start-hacking-on-openstack.html)
118
(This tutorial is based on:
119
http://www.linuxjedi.co.uk/2012/03/real-way-to-start-hacking-on-openstack.html)
100
120
101
121
Testing
102
122
-------
109
129
110
130
*Files: /tests/unit/**
111
131
112
The goal of unit tests is to ensure that internal parts of the code work properly.
113
All internal methods should be fully covered by unit tests with a reasonable mocks usage.
132
The goal of unit tests is to ensure that internal parts of the code work
133
properly. All internal methods should be fully covered by unit tests with a
134
reasonable mocks usage.
114
135
115
136
116
137
About Rally unit tests:
117
138
118
- All `unit tests <http://en.wikipedia.org/wiki/Unit_testing>`_ are located inside /tests/unit/*
139
- All `unit tests`_ are located inside /tests/unit/*
119
140
- Tests are written on top of: *testtools* and *mock* libs
120
- `Tox <https://tox.readthedocs.org/en/latest/>`_ is used to run unit tests
141
- `Tox`_ is used to run unit tests
121
142
122
143
123
144
To run unit tests locally:
184
205
185
206
*Files: /tests/functional/**
186
207
187
The goal of `functional tests <https://en.wikipedia.org/wiki/Functional_testing>`_ is to check that everything works well together.
188
Functional tests use Rally API only and check responses without touching internal parts.
208
The goal of `functional tests`_ is to check that everything works well
209
together. Functional tests use Rally API only and check responses without
210
touching internal parts.
189
211
190
212
To run functional tests locally:
191
213
200
222
Output of every Rally execution will be collected under some reports root in
201
223
directory structure like: reports_root/ClassName/MethodName_suffix.extension
202
224
This functionality implemented in tests.functional.utils.Rally.__call__ method.
203
Use 'gen_report_path' method of 'Rally' class to get automatically generated file
204
path and name if you need. You can use it to publish html reports, generated
205
during tests.
206
Reports root can be passed throw environment variable 'REPORTS_ROOT'. Default is
207
'rally-cli-output-files'.
225
Use 'gen_report_path' method of 'Rally' class to get automatically generated
226
file path and name if you need. You can use it to publish html reports,
227
generated during tests. Reports root can be passed throw environment variable
228
'REPORTS_ROOT'. Default is 'rally-cli-output-files'.
208
229
209
230
Rally CI scripts
210
231
^^^^^^^^^^^^^^^^
220
241
221
242
This module contains Rally specific hacking rules for checking commandments.
222
243
223
For more information about Style Commandments, read the `OpenStack Style Commandments manual <http://docs.openstack.org/developer/hacking/>`_.
244
For more information about Style Commandments, read the
245
`OpenStack Style Commandments manual`_.
246
247
.. references:
248
249
.. _our Roadmap: https://docs.google.com/a/mirantis.com/spreadsheets/d/16DXpfbqvlzMFaqaXAcJsBzzpowb_XpymaK2aFY2gA2g/edit#gid=0
250
.. _Rally-dev/Lobby: https://gitter.im/rally-dev/Lobby
251
.. _Launchpad: https://launchpad.net/
252
.. _OpenStack team: https://launchpad.net/openstack
253
.. _Rally team: https://launchpad.net/rally
254
.. _account setup: http://docs.openstack.org/infra/manual/developers.html#development-workflow
255
.. _review site: http://review.openstack.org/
256
.. _Jenkins setup: http://jenkins.openstack.org/
257
.. _unit tests: http://en.wikipedia.org/wiki/Unit_testing
258
.. _Tox: https://tox.readthedocs.org/en/latest/
259
.. _functional tests: https://en.wikipedia.org/wiki/Functional_testing
260
.. _OpenStack Style Commandments manual: http://docs.openstack.org/developer/hacking/
Loggerhead is a web-based interface for Breezy
Version: 2.0.1