From 8544eabcb99f3bc58052e722e8317ad7a9bfd620 Mon Sep 17 00:00:00 2001 From: Dina Belova Date: Tue, 6 Dec 2016 11:05:15 -0800 Subject: [PATCH] [docs][6] Re-design docs to cover all user-groups All information related to Rally community and project info has been refactored. Modified files fit 80 symbols margin where possible. [TODO] add 80 symbols margin check similar to what Performance Documentation has Change-Id: Id4f33733c2b9aa141df4eeb0f24a21d82290a962 --- CONTRIBUTING.rst | 1 + doc/feature_request/README.rst | 8 +- doc/feature_request/check_queue_perfdata.rst | 25 +++--- .../distributed_load_generation.rst | 3 +- doc/feature_request/installing_isolated.rst | 10 +-- .../launch_specific_benchmark.rst | 4 +- .../multiple_attach_volume.rst | 11 +-- .../production_ready_cleanup.rst | 5 +- doc/source/contribute.rst | 87 +++++++++++++------ doc/source/index.rst | 3 +- .../index.rst} | 47 +++++++--- doc/source/project_info/release_notes | 1 + .../{ => project_info}/release_notes.rst | 2 +- doc/source/release_notes | 1 - 14 files changed, 134 insertions(+), 74 deletions(-) create mode 120000 CONTRIBUTING.rst rename doc/source/{project_info.rst => project_info/index.rst} (85%) create mode 120000 doc/source/project_info/release_notes rename doc/source/{ => project_info}/release_notes.rst (98%) delete mode 120000 doc/source/release_notes diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 120000 index 0000000000..c5fee138cb --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1 @@ +doc/source/contribute.rst \ No newline at end of file diff --git a/doc/feature_request/README.rst b/doc/feature_request/README.rst index f975f91ec0..555c430cc9 100644 --- a/doc/feature_request/README.rst +++ b/doc/feature_request/README.rst @@ -2,8 +2,10 @@ Feature requests ================ -To request a new feature, you should create a document similar to other feature requests. And contribute it to this directory using the next instruction_. +To request a new feature, you should create a document similar to other feature +requests. And contribute it to this directory using the next instruction_. -If you don't have time to contribute your feature request via gerrit, please contact Boris Pavlovic (boris@pavlovic.me) +If you don't have time to contribute your feature request via Gerrit, please +contact Andrey Kurilin (andr.kurilin@gmail.com) -.. _instruction: http://rally.readthedocs.org/en/latest/contribute.html#how-to-contribute +.. _instruction: http://rally.readthedocs.org/en/latest/contribute.html#how-to-contribute diff --git a/doc/feature_request/check_queue_perfdata.rst b/doc/feature_request/check_queue_perfdata.rst index c09ff5a1d5..a95ed17954 100644 --- a/doc/feature_request/check_queue_perfdata.rst +++ b/doc/feature_request/check_queue_perfdata.rst @@ -1,19 +1,22 @@ -=========================== +==================== Check queue perfdata -=========================== - +==================== Use case -———— -Sometimes OpenStack services use common messaging system very prodigally. For example neutron metering agent sending all database table data on new object creation i.e https://review.openstack.org/#/c/143672/. It cause to neutron degradation and other obvious problems. -It will be nice to have a way to track messages count and messages size in queue during tests/benchmarks. - +-------- +Sometimes OpenStack services use common messaging system very prodigally. For +example Neutron metering agent sending all database table data on new object +creation i.e https://review.openstack.org/#/c/143672/. It cause to Neutron +degradation and other obvious problems. It will be nice to have a way to track +messages count and messages size in queue during tests/benchmarks. Problem description -————————— +------------------- + Heavy usage of queue isn’t checked. - Possible solution -———————— -* Before running tests/benchmarks start process which will connect to queue topics and measure messages count, size and other data which we need. +----------------- + +* Before running tests/benchmarks start process which will connect to queue +topics and measure messages count, size and other data which we need. diff --git a/doc/feature_request/distributed_load_generation.rst b/doc/feature_request/distributed_load_generation.rst index 72251d2e26..8abf946f62 100644 --- a/doc/feature_request/distributed_load_generation.rst +++ b/doc/feature_request/distributed_load_generation.rst @@ -11,10 +11,9 @@ like 10-100k request per second for benchmarking. To generate such huge load Rally have to create load from different servers. - Problem Description ------------------- * Rally can't generate load from different servers * Result processing can't handle big amount of data -* There is no support for chunking results \ No newline at end of file +* There is no support for chunking results diff --git a/doc/feature_request/installing_isolated.rst b/doc/feature_request/installing_isolated.rst index b89987cd8c..2d5025958d 100644 --- a/doc/feature_request/installing_isolated.rst +++ b/doc/feature_request/installing_isolated.rst @@ -1,15 +1,15 @@ -============================================================================= +================================================================================= Installation script: ``--pypi-mirror``, ``--package-mirror`` and ``--venv-mirror`` -============================================================================= +================================================================================= Use case -------- Installation is pretty easy when there is an Internet connection available. -And there is surely a number of OpenStack uses when whole environment is isolated. -In this case, we need somehow specify where installation script should take -required libs and packages. +And there is surely a number of OpenStack uses when whole environment is +isolated. In this case, we need somehow specify where installation script +should take required libs and packages. Problem description diff --git a/doc/feature_request/launch_specific_benchmark.rst b/doc/feature_request/launch_specific_benchmark.rst index 21008f5275..0b910c4ead 100644 --- a/doc/feature_request/launch_specific_benchmark.rst +++ b/doc/feature_request/launch_specific_benchmark.rst @@ -8,7 +8,7 @@ Use case A developer is working on a feature that is covered by one or more specific benchmarks/scenarios. He/she would like to execute a rally task with an -existing task template file (yaml or json) indicating exactly which +existing task template file (YAML or JSON) indicating exactly which benchmark(s) will be executed. @@ -24,4 +24,4 @@ Possible solution ----------------- * Add optional flag to rally task start command to specify one or more -benchmarks to execute as part of that test run. \ No newline at end of file +benchmarks to execute as part of that test run. diff --git a/doc/feature_request/multiple_attach_volume.rst b/doc/feature_request/multiple_attach_volume.rst index f3a50d83ed..700b1fb3f8 100644 --- a/doc/feature_request/multiple_attach_volume.rst +++ b/doc/feature_request/multiple_attach_volume.rst @@ -1,17 +1,18 @@ -==================== +====================== Multiple attach volume -==================== +====================== Use Case -------- -Since multiple volume attaching support to OpenStack Mitaka, one volume can be attached to several -instances or hosts, rally should add scenarios about multiple attach volume. +Since multiple volume attaching support to OpenStack Mitaka, one volume can be +attached to several instances or hosts, Rally should add scenarios about +multiple attach volume. Problem Description ------------------- -Rally lack of scenarios about multiple attach volume +Rally lack of scenarios about multiple attach volume. Possible solution diff --git a/doc/feature_request/production_ready_cleanup.rst b/doc/feature_request/production_ready_cleanup.rst index d74003dc38..318518dfa1 100644 --- a/doc/feature_request/production_ready_cleanup.rst +++ b/doc/feature_request/production_ready_cleanup.rst @@ -32,6 +32,5 @@ Problem Description * Disaster recovery Rally should use special name patterns, to be able to delete resources - in such case if something went wrong with server that is running rally. And - you have just new instance (without old rally db) of rally on new server. - + in such case if something went wrong with server that is running Rally. And + you have just new instance (without old Rally DB) of Rally on new server. diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst index 6af0c5b82d..2d22343a9b 100644 --- a/doc/source/contribute.rst +++ b/doc/source/contribute.rst @@ -21,19 +21,27 @@ Contribute to Rally Where to begin -------------- -Please take a look `our Roadmap `_ to get information about our current work directions. +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 at the ``#openstack-rally`` IRC channel on **irc.freenode.net**. +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 **benchmark scenarios**, **contexts** etc.). To do so, please read :ref:`this article `. +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 `. 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. +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. +2. Sign the CLA as outlined in the `account setup`_ section of the developer guide. 3. Tell git your details: @@ -42,13 +50,17 @@ How to contribute 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: +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. +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: @@ -64,7 +76,8 @@ Several Linux distributions (notably Fedora 16 and Ubuntu 12.04) are also starti 7. Start coding -8. Run the test suite locally to make sure nothing broke, e.g. (this will run py34/py27/pep8 tests): +8. Run the test suite locally to make sure nothing broke, e.g. (this will run +py34/py27/pep8 tests): .. code-block:: bash @@ -72,7 +85,8 @@ Several Linux distributions (notably Fedora 16 and Ubuntu 12.04) are also starti **(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. +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: @@ -81,7 +95,8 @@ If you extend Rally with new functionality, make sure you have also provided uni 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. +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: @@ -89,14 +104,19 @@ Make sure you have supplied your commit with a neat commit message, containing a git review -R -That is the awesome tool we installed earlier that does a lot of hard work for you. +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. +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) +(This tutorial is based on: +http://www.linuxjedi.co.uk/2012/03/real-way-to-start-hacking-on-openstack.html) Testing ------- @@ -109,15 +129,16 @@ 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. +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/* +- 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 +- `Tox`_ is used to run unit tests To run unit tests locally: @@ -184,8 +205,9 @@ 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. +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: @@ -200,11 +222,10 @@ To run functional tests locally: 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'. +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 ^^^^^^^^^^^^^^^^ @@ -220,4 +241,20 @@ Rally Style Commandments This module contains Rally specific hacking rules for checking commandments. -For more information about Style Commandments, read the `OpenStack Style Commandments manual `_. +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: http://docs.openstack.org/infra/manual/developers.html#development-workflow +.. _review site: http://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: http://docs.openstack.org/developer/hacking/ diff --git a/doc/source/index.rst b/doc/source/index.rst index efb521f531..59583684ba 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -45,5 +45,4 @@ Contents plugins/index contribute feature_requests - project_info - release_notes + project_info/index diff --git a/doc/source/project_info.rst b/doc/source/project_info/index.rst similarity index 85% rename from doc/source/project_info.rst rename to doc/source/project_info/index.rst index a8f2811e20..2a69c97651 100644 --- a/doc/source/project_info.rst +++ b/doc/source/project_info/index.rst @@ -15,8 +15,8 @@ .. _project_info: -Project Info -============ +Project Info and Release Notes +============================== Maintainers ----------- @@ -123,20 +123,39 @@ Plugin Core reviewers Useful links ------------ -- `Source code `_ -- `Rally road map `_ -- `Project space `_ -- `Bugs `_ -- `Patches on review `_ -- `Meeting logs `_ (server: **irc.freenode.net**, channel: **#openstack-meeting**) -- `IRC logs `_ (server: **irc.freenode.net**, channel: **#openstack-rally**) -- `Gitter chat `_ -- `Trello board `_ +- `Source code`_ +- `Rally roadmap`_ +- `Project space`_ +- `Bugs`_ +- `Patches on review`_ +- `Meeting logs`_ (server: **irc.freenode.net**, channel: + **#openstack-meeting**) +- `IRC logs`_ (server: **irc.freenode.net**, channel: **#openstack-rally**) +- `Gitter chat`_ +- `Trello board`_ Where can I discuss and propose changes? ---------------------------------------- - Our IRC channel: **#openstack-rally** on **irc.freenode.net**; -- Weekly Rally team meeting (in IRC): **#openstack-meeting** on **irc.freenode.net**, held on Mondays at 14:00 UTC; -- OpenStack mailing list: **openstack-dev@lists.openstack.org** (see `subscription and usage instructions `_); -- `Rally team on Launchpad `_: Answers/Bugs/Blueprints. +- Weekly Rally team meeting (in IRC): **#openstack-meeting** on + **irc.freenode.net**, held on Mondays at 14:00 UTC; +- OpenStack mailing list: **openstack-dev@lists.openstack.org** (see + `subscription and usage instructions`_); +- `Rally team on Launchpad`_: Answers/Bugs/Blueprints. + +.. include:: release_notes.rst + +.. references: + +.. _Source code: https://github.com/openstack/rally +.. _Rally roadmap: https://docs.google.com/a/mirantis.com/spreadsheets/d/16DXpfbqvlzMFaqaXAcJsBzzpowb_XpymaK2aFY2gA2g/edit#gid=0 +.. _Project space: http://launchpad.net/rally +.. _Bugs: https://bugs.launchpad.net/rally +.. _Patches on review: https://review.openstack.org/#/q/status:open+rally,n,z +.. _Meeting logs: http://eavesdrop.openstack.org/meetings/rally/2016/ +.. _IRC logs: http://irclog.perlgeek.de/openstack-rally +.. _Gitter chat: https://gitter.im/rally-dev/Lobby +.. _Trello board: https://trello.com/b/DoD8aeZy/rally +.. _subscription and usage instructions: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev +.. _Rally team on Launchpad: https://launchpad.net/rally diff --git a/doc/source/project_info/release_notes b/doc/source/project_info/release_notes new file mode 120000 index 0000000000..26544e47ef --- /dev/null +++ b/doc/source/project_info/release_notes @@ -0,0 +1 @@ +../../release_notes/ \ No newline at end of file diff --git a/doc/source/release_notes.rst b/doc/source/project_info/release_notes.rst similarity index 98% rename from doc/source/release_notes.rst rename to doc/source/project_info/release_notes.rst index 7baa90dabe..811c5e424c 100644 --- a/doc/source/release_notes.rst +++ b/doc/source/project_info/release_notes.rst @@ -16,7 +16,7 @@ .. _release_notes: Release Notes -============= +------------- .. toctree:: :maxdepth: 1 diff --git a/doc/source/release_notes b/doc/source/release_notes deleted file mode 120000 index 0d20509abd..0000000000 --- a/doc/source/release_notes +++ /dev/null @@ -1 +0,0 @@ -../release_notes \ No newline at end of file