openstack/rally
Code Issues Proposed changes

Fix contribute page

Browse Source 
Change-Id: I3a3c4e215724b955f168ce4f97a215aa148ff5d0
This commit is contained in:
Andrey Kurilin 2021-06-16 18:19:25 +03:00
parent e67de57707
commit 1d9c1e82f3
4 changed files with 43 additions and 299 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CONTRIBUTING.rst
View File

@ -16,4 +16,4 @@ Bugs should be filed on Launchpad:
For more specific information about contributing to this repository, see the
rally contributor guide:
https://docs.openstack.org/rally/latest/contributor/contributing.html
https://rally.readthedocs.io/en/latest/contribute.html

284
doc/source/contribute.rst
View File

@ -1,5 +1,4 @@
..
Copyright 2015 Mirantis Inc. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
@ -18,244 +17,45 @@
Contribute to Rally
===================
Where to begin
--------------
Please take a look `our Roadmap`_ to get information about our current work
directions.
In case you have questions or want to share your ideas, be sure to contact us
either at `Rally-dev/Lobby`_ channel on **Gitter** messenger (or, less
preferably, at the ``#openstack-rally`` IRC channel on **irc.freenode.net**).
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 **scenarios**, **contexts** etc.). To do so, please
read :ref:`this article <main_concepts>`.
How to contribute
-----------------
1. You need a `Launchpad`_ account and need to be joined to the
`OpenStack team`_. You can also join the `Rally team`_ if you want to. Make
sure Launchpad has your SSH key, Gerrit (the code review system) uses this.
2. Sign the CLA as outlined in the `account setup`_ section of the developer
guide.
3. Tell git your details:
.. code-block:: bash
git config --global user.name "Firstname Lastname"
git config --global user.email "your_email@youremail.com"
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:
.. code-block:: bash
pip install git-review
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.
5. Grab the Rally repository:
.. code-block:: bash
git clone git@github.com:openstack/rally.git
6. Checkout a new branch to hack on:
.. code-block:: bash
git checkout -b TOPIC-BRANCH
7. Start coding
8. Run the test suite locally to make sure nothing broke, e.g. (this will run
py34/py27/pep8 tests):
.. code-block:: bash
tox
**(NOTE: you should have installed tox<=1.6.1)**
If you extend Rally with new functionality, make sure you have also provided
unit and/or functional tests for it.
9. Commit your work using:
.. code-block:: bash
git commit -a
Make sure you have supplied your commit with a neat commit message, containing
a link to the corresponding blueprint / bug, if appropriate.
10. Push the commit up for code review using:
.. code-block:: bash
git review -R
That is the awesome tool we installed earlier that does a lot of hard work for
you.
11. Watch your email or `review site`_, it will automatically send your code
for a battery of tests on our `Jenkins setup`_ 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.
12. When all is good the review site will automatically merge your code.
(This tutorial is based on:
http://www.linuxjedi.co.uk/2012/03/real-way-to-start-hacking-on-openstack.html)
Testing
-------
Please, don't hesitate to write tests ;)
Unit tests
^^^^^^^^^^
*Files: /tests/unit/**
The goal of unit tests is to ensure that internal parts of the code work
properly. All internal methods should be fully covered by unit tests with a
reasonable mocks usage.
About Rally unit tests:
- All `unit tests`_ are located inside /tests/unit/*
- Tests are written on top of: *testtools* and *mock* libs
- `Tox`_ is used to run unit tests
To run unit tests locally:
.. code-block:: console
$ pip install tox
$ tox
To run py34, py27 or pep8 only:
.. code-block:: console
$ tox -e <name>
#NOTE: <name> is one of py34, py27 or pep8
To run a single unit test e.g. test_deployment
.. code-block:: console
$ tox -e <name> -- <test_name>
#NOTE: <name> is one of py34, py27 or pep8
# <test_name> is the unit test case name, e.g tests.unit.test_osclients
To debug issues on the unit test:
- Add breakpoints on the test file using ``import pdb;`` ``pdb.set_trace()``
- Then run tox in debug mode:
.. code-block:: console
$ tox -e debug <test_name>
#NOTE: use python 2.7
#NOTE: <test_name> is the unit test case name
or
.. code-block:: console
$ tox -e debug34 <test_name>
#NOTE: use python 3.4
#NOTE: <test_name> is the unit test case name
To get test coverage:
.. code-block:: console
$ tox -e cover
#NOTE: Results will be in /cover/index.html
To generate docs:
.. code-block:: console
$ tox -e docs
#NOTE: Documentation will be in doc/source/_build/html/index.html
Functional tests
^^^^^^^^^^^^^^^^
*Files: /tests/functional/**
The goal of `functional tests`_ is to check that everything works well
together. Functional tests use Rally API only and check responses without
touching internal parts.
To run functional tests locally:
.. code-block:: console
$ source openrc
$ rally deployment create --fromenv --name testing
$ tox -e cli
#NOTE: openrc file with OpenStack admin credentials
Output of every Rally execution will be collected under some reports root in
directory structure like: reports_root/ClassName/MethodName_suffix.extension
This functionality implemented in tests.functional.utils.Rally.__call__ method.
Use 'gen_report_path' method of 'Rally' class to get automatically generated
file path and name if you need. You can use it to publish html reports,
generated during tests. Reports root can be passed throw environment variable
'REPORTS_ROOT'. Default is 'rally-cli-output-files'.
Rally CI scripts
^^^^^^^^^^^^^^^^
*Files: /tests/ci/**
This directory contains scripts and files related to the Rally CI system.
Rally Style Commandments
^^^^^^^^^^^^^^^^^^^^^^^^
*Files: /tests/hacking/*
This module contains Rally specific hacking rules for checking commandments.
For more information about Style Commandments, read the
`OpenStack Style Commandments manual`_.
.. references:
.. _our Roadmap: https://docs.google.com/a/mirantis.com/spreadsheets/d/16DXpfbqvlzMFaqaXAcJsBzzpowb_XpymaK2aFY2gA2g/edit#gid=0
.. _Rally-dev/Lobby: https://gitter.im/rally-dev/Lobby
.. _Launchpad: https://launchpad.net/
.. _OpenStack team: https://launchpad.net/openstack
.. _Rally team: https://launchpad.net/rally
.. _account setup: https://docs.openstack.org/infra/manual/developers.html#development-workflow
.. _review site: https://review.openstack.org/
.. _Jenkins setup: http://jenkins.openstack.org/
.. _unit tests: http://en.wikipedia.org/wiki/Unit_testing
.. _Tox: https://tox.readthedocs.org/en/latest/
.. _functional tests: https://en.wikipedia.org/wiki/Functional_testing
.. _OpenStack Style Commandments manual: https://docs.openstack.org/hacking/latest/
For general information on contributing to OpenStack, please check out the
`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
It covers all the basics that are common to all OpenStack projects:
the accounts you need, the basics of interacting with our Gerrit review system,
how we communicate as a community, etc.
Below will cover the more project specific information you need to get started
with Rally.
Communication
~~~~~~~~~~~~~
* Gitter channel https://gitter.im/xRally/Lobby
* IRC channel #openstack-rally at OFTC
* Mailing list (prefix subjects with ``[rally]`` for faster responses)
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
Contacting the Core Team
~~~~~~~~~~~~~~~~~~~~~~~~
Please refer the `Rally Core Team
<https://review.opendev.org/admin/groups/b809b67b705ecb181cef2e1e68e06cac5c61882b>`_
contacts.
Task Tracking
~~~~~~~~~~~~~
We track our tasks in `Launchpad <https://bugs.launchpad.net/rally>`_.
If you're looking for some smaller, easier work item to pick up and get started
on, search for the 'low-hanging-fruit' tag.
Reporting a Bug
~~~~~~~~~~~~~~~
You found an issue and want to make sure we are aware of it? You can do so on
`Launchpad <https://bugs.launchpad.net/rally>`_.
Getting Your Patch Merged
~~~~~~~~~~~~~~~~~~~~~~~~~
All changes proposed to the Rally project require one or two +2 votes
from Rally core reviewers before one of the core reviewers can approve
patch by giving ``Workflow +1`` vote.
Project Team Lead Duties
~~~~~~~~~~~~~~~~~~~~~~~~
All common PTL duties are enumerated in the `PTL guide
<https://docs.openstack.org/project-team-guide/ptl.html>`_.

48
doc/source/contributor/contributing.rst
View File

@ -1,48 +0,0 @@
============================
So You Want to Contribute...
============================
For general information on contributing to OpenStack, please check out the
`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
It covers all the basics that are common to all OpenStack projects: the accounts
you need, the basics of interacting with our Gerrit review system, how we
communicate as a community, etc.
Below will cover the more project specific information you need to get started
with Rally.
Communication
~~~~~~~~~~~~~
* Gitter channel https://gitter.im/xRally/Lobby
* IRC channel #openstack-rally at OFTC
* Mailing list (prefix subjects with ``[rally]`` for faster responses)
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
Contacting the Core Team
~~~~~~~~~~~~~~~~~~~~~~~~
Please refer the `rally Core Team
<https://review.opendev.org/admin/groups/b809b67b705ecb181cef2e1e68e06cac5c61882b>`_ contacts.
New Feature Planning
~~~~~~~~~~~~~~~~~~~~
rally features are tracked on `Launchpad <https://bugs.launchpad.net/rally>`_.
Task Tracking
~~~~~~~~~~~~~
We track our tasks in `Launchpad <https://bugs.launchpad.net/rally>`_.
If you're looking for some smaller, easier work item to pick up and get started
on, search for the 'low-hanging-fruit' tag.
Reporting a Bug
~~~~~~~~~~~~~~~
You found an issue and want to make sure we are aware of it? You can do so on
`Launchpad <https://bugs.launchpad.net/rally>`_.
Getting Your Patch Merged
~~~~~~~~~~~~~~~~~~~~~~~~~
All changes proposed to the rally project require one or two +2 votes
from rally core reviewers before one of the core reviewers can approve
patch by giving ``Workflow +1`` vote.
Project Team Lead Duties
~~~~~~~~~~~~~~~~~~~~~~~~
All common PTL duties are enumerated in the `PTL guide
<https://docs.openstack.org/project-team-guide/ptl.html>`_.

8
doc/source/index.rst
View File

@ -49,15 +49,7 @@ Contents
For Contributors
================
* If you are a new contributor to Rally please refer: :doc:`contributor/contributing`
.. toctree::
:hidden:
contributor/contributing
.. toctree::
:maxdepth: 2
contribute