diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index ef585fb15a..e6cfadd4f5 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst index dd64489a83..245a8e52ca 100644 --- a/doc/source/contribute.rst +++ b/doc/source/contribute.rst @@ -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 `. - - -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 - - #NOTE: is one of py34, py27 or pep8 - -To run a single unit test e.g. test_deployment - -.. code-block:: console - - $ tox -e -- - - #NOTE: is one of py34, py27 or pep8 - # 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 - #NOTE: use python 2.7 - #NOTE: is the unit test case name - - or - -.. code-block:: console - - $ tox -e debug34 - #NOTE: use python 3.4 - #NOTE: 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 `_ 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 +`_ +contacts. + +Task Tracking +~~~~~~~~~~~~~ +We track our tasks in `Launchpad `_. +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 `_. + +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 +`_. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst deleted file mode 100644 index ed58806f70..0000000000 --- a/doc/source/contributor/contributing.rst +++ /dev/null @@ -1,48 +0,0 @@ -============================ -So You Want to Contribute... -============================ -For general information on contributing to OpenStack, please check out the -`contributor guide `_ 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 -`_ contacts. - -New Feature Planning -~~~~~~~~~~~~~~~~~~~~ -rally features are tracked on `Launchpad `_. - -Task Tracking -~~~~~~~~~~~~~ -We track our tasks in `Launchpad `_. -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 `_. - -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 -`_. diff --git a/doc/source/index.rst b/doc/source/index.rst index a6184dea29..ec9c0e21c1 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 -