From d7fdee30cc070bc4e3c4718b1a189e13da8818b5 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 +- doc/source/project_info/index.rst | 161 ++++++++++++++++++ doc/source/project_info/release_notes | 1 + doc/source/project_info/release_notes.rst | 26 +++ 13 files changed, 287 insertions(+), 58 deletions(-) create mode 120000 CONTRIBUTING.rst create mode 100644 doc/source/project_info/index.rst create mode 120000 doc/source/project_info/release_notes create mode 100644 doc/source/project_info/release_notes.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 120000 index 00000000..c5fee138 --- /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 f975f91e..555c430c 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 c09ff5a1..a95ed179 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 72251d2e..8abf946f 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 b89987cd..2d502595 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 21008f52..0b910c4e 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 f3a50d83..700b1fb3 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 d74003dc..318518df 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 6af0c5b8..2d22343a 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 efb521f5..59583684 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/index.rst b/doc/source/project_info/index.rst new file mode 100644 index 00000000..2a69c976 --- /dev/null +++ b/doc/source/project_info/index.rst @@ -0,0 +1,161 @@ +.. + 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 + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _project_info: + +Project Info and Release Notes +============================== + +Maintainers +----------- + +Project Team Lead (PTL) +~~~~~~~~~~~~~~~~~~~~~~~ + + ++------------------------------+------------------------------------------------+ +| Contact | Area of interest | ++------------------------------+------------------------------------------------+ +| | Andrey Kurilin | * Road Map | +| | andreykurilin (irc) | * Release management | +| | andr.kurilin@gmail.com | * Community management | +| | akurilin@mirantis.com | * Core team management | +| | * Chief Architect | ++------------------------------+------------------------------------------------+ + +| *If you would like to refactor whole Rally or have UX/community/other + issues please contact me.* + + +Project Core maintainers +~~~~~~~~~~~~~~~~~~~~~~~~ + ++------------------------------+------------------------------------------------+ +| Contact | Area of interest | ++------------------------------+------------------------------------------------+ +| | Alexander Maretskiy | * Rally reports | +| | amaretskiy (irc) | * Front-end | +| | amaretskiy@mirantis.com | | ++------------------------------+------------------------------------------------+ +| | Boris Pavlovic | * Founder and ideological leader | +| | boris-42 (irc) | * Architect | +| | boris@pavlovic.me | * Rally task & benchmark | ++------------------------------+------------------------------------------------+ +| | Chris St. Pierre | * Rally task & benchmark | +| | stpierre (irc) | * Bash guru ;) | +| | cstpierr@cisco.com | | ++------------------------------+------------------------------------------------+ +| | Illia Khudoshyn | * Rally task & benchmark | +| | ikhudoshyn (irc) | | +| | ikhudoshyn@mirantis.com | | ++------------------------------+------------------------------------------------+ +| | Kun Huang | * Rally task & benchmark | +| | kun_huang (irc) | | +| | gareth.huang@huawei.com | | ++------------------------------+------------------------------------------------+ +| | Li Yingjun | * Rally task & benchmark | +| | liyingjun (irc) | | +| | yingjun.li@kylin-cloud.com | | ++------------------------------+------------------------------------------------+ +| | Roman Vasilets | * Rally task & benchmark | +| | rvasilets (irc) | | +| | rvasilets@mirantis.com | | ++------------------------------+------------------------------------------------+ +| | Sergey Skripnick | * Rally CI/CD | +| | redixin (irc) | * Rally deploy | +| | sskripnick@mirantis.com | * Automation of everything | ++------------------------------+------------------------------------------------+ +| | Yair Fried | * Rally-Tempest integration | +| | yfried (irc) | * Rally task & benchmark | +| | yfried@redhat.com | | ++------------------------------+------------------------------------------------+ + +| *All cores from this list are reviewing all changes that are proposed to Rally. + To avoid duplication of efforts, please contact them before starting work on + your code.* + + +Plugin Core reviewers +~~~~~~~~~~~~~~~~~~~~~ + ++------------------------------+------------------------------------------------+ +| Contact | Area of interest | ++------------------------------+------------------------------------------------+ +| | Ivan Kolodyazhny | * Cinder plugins | +| | e0ne (irc) | | +| | e0ne@e0ne.info | | ++------------------------------+------------------------------------------------+ +| | Nikita Konovalov | * Sahara plugins | +| | NikitaKonovalov (irc) | | +| | nkonovalov@mirantis.com | | ++------------------------------+------------------------------------------------+ +| | Oleg Bondarev | * Neutron plugins | +| | obondarev (irc) | | +| | obondarev@mirantis.com | | ++------------------------------+------------------------------------------------+ +| | Sergey Kraynev | * Heat plugins | +| | skraynev (irc) | | +| | skraynev@mirantis.com | | ++------------------------------+------------------------------------------------+ +| | Yaroslav Lobankov | * Rally Verification | +| | ylobankov (irc) | | +| | ylobankov@mirantis.com | | ++------------------------------+------------------------------------------------+ + + + +| *All cores from this list are responsible for their component plugins. + To avoid duplication of efforts, please contact them before starting working + on your own plugins.* + + +Useful links +------------ +- `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. + +.. 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 00000000..26544e47 --- /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/project_info/release_notes.rst b/doc/source/project_info/release_notes.rst new file mode 100644 index 00000000..811c5e42 --- /dev/null +++ b/doc/source/project_info/release_notes.rst @@ -0,0 +1,26 @@ +.. + 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 + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _release_notes: + +Release Notes +------------- + +.. toctree:: + :maxdepth: 1 + + release_notes/archive.rst + release_notes/latest.rst +