diff --git a/doc/doc-contrib-guide/source/doc-bugs.rst b/doc/doc-contrib-guide/source/doc-bugs.rst index 3e83590d23..dc4fdb0d3c 100644 --- a/doc/doc-contrib-guide/source/doc-bugs.rst +++ b/doc/doc-contrib-guide/source/doc-bugs.rst @@ -4,35 +4,98 @@ Documentation bugs ================== -The Documentation team tracks all its work through bugs. This section includes -the detailed overview of documentation bugs specifics. +The Documentation team tracks some of its work through bugs. This section +includes the detailed overview of documentation bugs specifics. The Documentation team uses the following projects for tracking documentation -bugs across OpenStack: +bugs for repositories managed by the Documentation project or the project's +subteams: * `openstack-manuals `_ is the default area for doc bugs in the openstack-manuals repository. +* `openstack-api-site `_ is used + for the api-site API repository. + +* `openstack-contributor-guide `_ + is used for the contributor-guide repository. + * `OpenStack Security Guide Documentation `_ is used for the security-doc repository. -* `openstack-api-site `_ is used - for the api-site API repository. - * `openstack-doc-tools `_ is used for the doc-tools and openstackdocstheme repositories. +Documentation bugs for project-specific repositories are tracked in the +appropriate project's bug tracking area on Launchpad. + .. toctree:: :maxdepth: 2 doc-impact.rst +Filing a bug +~~~~~~~~~~~~ + +Bugs differ depending on: + +* The way they are filed: + + * Manually + * Automatically (through the DocImpact flag) + +* The required changes: + + * Fix spelling errors or formatting + * Update existing content + * Add new content + +.. important:: + + Do not file a bug with troubleshooting issues. If you are experiencing + problems with your environment, and you are following the installation + tutorials, seek assistance from the relevant team and operations + specialists on IRC, + `ask.openstack.org `_ + or the OpenStack mailing list. + + For more information about the relevant IRC channels, see the + `OpenStack IRC wiki `_. + + For more information about the OpenStack mailing list, see the + `Mailing lists wiki `_. + + A bug should be filed only if the documentation itself is found to be + incorrect. + +Working on documentation bugs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Do not work on a documentation bug until it is set to +'Confirmed'. Ideally, someone other than the reporter will confirm the bug +for you. Once the changes are made in a patch, they are reviewed and approved, +just like other OpenStack code. + +To pick up a documentation bug or mark a bug as related to the +documentation, go to `the aggregated list of documentation bugs from all +OpenStack projects +`_. + +Triaging bugs for openstack-manuals +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following sections detail the role of the bug triage liaison and the +process and guidelines of bug triaging for the openstack-manuals repository. + +Project-specific repositories follow their respective team's processes and +guidelines for bug triaging. + Bug triage liaison -~~~~~~~~~~~~~~~~~~ +------------------ The documentation team assigns bug triage liaisons to ensure all bugs reported -against OpenStack manuals are triaged in a timely manner. +against the openstack-manuals repository are triaged in a timely manner. If you are interested in serving as a bug triage liaison, there are several steps you will need to follow in order to be prepared. @@ -49,7 +112,8 @@ steps you will need to follow in order to be prepared. #. Sign up for openstack-manuals emails from Launchpad if you have not already: - #. Navigate to the Launchpad openstack-manuals bug list. + #. Navigate to the `Launchpad openstack-manuals bug list + `_. #. Click on the right hand side, :guilabel:`Subscribe to bug mail`. #. In the pop-up that is displayed, keep the recipient as :guilabel:`Yourself`, and name your subscription something useful @@ -58,28 +122,32 @@ steps you will need to follow in order to be prepared. mail for all changes - while informative - will result in several dozen emails per day at least. -#. Volunteer during the course of the Docs team meeting, when volunteers to - be bug deputy are requested (usually towards the beginning of the meeting). +#. Volunteer during the course of the Documentation team meeting, when + volunteers to be bug deputy are requested. -#. View your scheduled week on the - `Bug Triage Team `_ + Alternatively, use the #openstack-doc IRC channel or the + openstack-dev@lists.openstack.org mailing list to contact the documentation + core team members. + +#. Sign up as a volunteer by adding your name to the bug triaging schedule on the + `Bug Triage Team + `_ page. #. During your scheduled time as a liaison, if it is feasible for your - timezone, plan on attending the Docs team meeting. That way if you have - any CRITICAL or HIGH bugs, you can address them with the team. + timezone, plan on attending the Documentation team meeting. That way if you + have any CRITICAL or HIGH bugs, you can address them with the team. Bug triaging process -~~~~~~~~~~~~~~~~~~~~ +-------------------- The process of bug triaging consists of the following steps: * Check if a bug was filed for a correct component (project). If not, either change the project or mark it as ``Invalid``. For example, if the bug impacts the project-specific dev-ref, then - mark it as ``Invalid``. If a bug is reported against the nova section - of the Installation Guide, ensure openstack-manuals is removed, and - the nova project is added. + mark it as ``Invalid``. If a bug is reported against the nova installation + guide, ensure openstack-manuals is removed, and the nova project is added. * If the reported bug affects the ReST API, tools, openstackdocstheme, or the Security Guide, add the relevant project to the affected @@ -88,8 +156,8 @@ The process of bug triaging consists of the following steps: ``openstack-api-site`` and remove ``openstack-manuals``. * Tag the bug for the appropriate guide. For example, for the - ``networking-guide`` remove ``neutron`` from the affected projects if it - only affects ``openstack-manuals`` and tag ``networking-guide``. + ``image-guide`` remove ``glance`` from the affected projects if it + only affects ``openstack-manuals`` and tag ``image-guide``. * Set the bug to ``Invalid`` if it is a request for support or a troubleshooting request. @@ -163,7 +231,7 @@ Depending on the area a bug affects, it has one or more tags. For example: * **low-hanging-fruit** for documentation bugs that are straightforward to fix. If you are a newcomer, this is a way to start. -* **sec guide**, **install guide**, **ops-guide**, and other for specific +* **ha-guide**, **install-guide**, **image-guide**, and other for specific guides. * **infra**, **theme** for documentation bugs that are in the documentation @@ -173,8 +241,8 @@ Tracking bugs by tag -------------------- If you need to regularly track activity relating to particular tags, -you can set up email subscriptions by visiting `the subscriptions page -of the launchpad project +you can set up email subscriptions by visiting +`the subscriptions page of the Launchpad project `_: #. Select :guilabel:`Add a subscription`. @@ -208,50 +276,3 @@ committer of the change that triggered the bug report, mark it as **Wishlist** and ask the committer to read and follow the specification and handle it since the documentation team will not document third-party drivers. - -Filing a bug -~~~~~~~~~~~~ - -Bugs differ depending on: - -* The way they are filed: - - * Manually - * Automatically (through the DocImpact flag) - -* The required changes: - - * Fix spelling errors or formatting - * Update existing content - * Add new content - -.. important:: - - Do not file a bug with troubleshooting issues. If you are experiencing - problems with your environment, and you are following the installation - tutorials, seek assistance from the relevant team and operations - specialists on IRC, - `ask.openstack.org `_ - or the OpenStack mailing list. - - For more information about the relevant IRC channels, see the - `OpenStack IRC wiki `_. - - For more information about the OpenStack mailing list, see the - `Mailing lists wiki `_. - - A bug should be filed only if the documentation itself is found to be - incorrect. - -Working on documentation bugs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Do not work on a documentation bug until it is set to -'Confirmed'. Ideally, someone other than the reporter will confirm the bug -for you. Once the changes are made in a patch, they are reviewed and approved, -just like other OpenStack code. - -To pick up a documentation bug or mark a bug as related to the -documentation, go to `the aggregated list of documentation bugs from all -OpenStack projects -`_. diff --git a/doc/doc-contrib-guide/source/doc-impact.rst b/doc/doc-contrib-guide/source/doc-impact.rst index bb1781a400..c566e50acb 100644 --- a/doc/doc-contrib-guide/source/doc-impact.rst +++ b/doc/doc-contrib-guide/source/doc-impact.rst @@ -19,13 +19,14 @@ a deprecated or new feature, a caveat or if you have written docs in the patch, add "DocImpact" to a line in your commit message. This creates a Launchpad bug for the project indicated in the -``gerrit/projects.yaml`` file in the ``openstack/project-config`` repository. +``gerrit/projects.yaml`` file in the `openstack-infra/project-config +`_ repository. This does not guarantee documentation will be written, but offers visibility of the change and tracking. You can also use it as a reminder to yourself to write docs for the feature later, or remind yourself to find a writer to write for you. -If you are a doc contributor, these are the steps we take once a DocImpact +If you are a doc contributor, these are the steps we take once a ``DocImpact`` notification comes to the list. #. Create a new doc bug in either ``openstack-manuals`` or @@ -42,8 +43,8 @@ notification comes to the list. #. Continue to check on the patch and change the status to ``Confirmed`` once merged. -#. Use the information in the Doc bug triaging :ref:`guidelines` section to set - priority once it lands. +#. Use the information in the :ref:`guidelines` section to set priority once it + lands. Writing good commit messages for DocImpact ------------------------------------------ @@ -74,11 +75,11 @@ but extra usage information is useful. Third-Party DocImpact settings ------------------------------ -By default, the DocImpact tag creates bugs using the repository name as project -in Launchpad. To change this behaviour, the ``docimpact-group`` option in -``projects.yaml`` can be used. For example, if you set project like this: +By default, the ``DocImpact`` tag creates bugs using the repository name as +project in Launchpad. To change this behavior, the ``docimpact-group`` option +in ``projects.yaml`` can be used. For example, if you set project like this: -.. code-block: yaml +.. code-block:: yaml - project: stackforge/project-name description: Latest and greatest cloud stuff. diff --git a/doc/doc-contrib-guide/source/topic-tags.rst b/doc/doc-contrib-guide/source/topic-tags.rst index 8faae5a395..31cea25cfb 100644 --- a/doc/doc-contrib-guide/source/topic-tags.rst +++ b/doc/doc-contrib-guide/source/topic-tags.rst @@ -4,34 +4,20 @@ Topic tags ========== -We recommend that you add the tags in the head of the git commit -message or email subject line to show the topic explicitly. -Based on the topic your request refers to, use the following tags: - -[admin-guide] - OpenStack Administrator Guide - -[api] - OpenStack API Guide, API Complete References +When changing or discussing the contents of the openstack-manuals repository, +we recommend that you add the tags in the head of the git commit message or +email subject line to show the topic explicitly. Based on the topic you refer +to, use the following tags: [arch-design] OpenStack Architecture Design Guide -[cli-ref] - OpenStack Command-Line Interface Reference - [common] Common contents for several guides in the common directory -[config-ref] - OpenStack Configuration Reference - -[contributor] +[doc-contrib] OpenStack Documentation Contributor Guide -[firstapp] - Writing your first OpenStack application - [ha-guide] OpenStack High Availability Guide @@ -41,18 +27,6 @@ Based on the topic your request refers to, use the following tags: [install] OpenStack Installation Guides -[networking] - OpenStack Networking Guide - -[ops-guide] - OpenStack Operations Guide - -[sec-guide] - Security Guide - -[training] - Training labs, Training guides, and Upstream Training materials - [WIP] A marker that means the commit is a work in progress diff --git a/doc/ha-guide/source/index.rst b/doc/ha-guide/source/index.rst index ff25288296..3a8272f780 100644 --- a/doc/ha-guide/source/index.rst +++ b/doc/ha-guide/source/index.rst @@ -23,14 +23,15 @@ and assumes that you are familiar with the material in those guides. The OpenStack HA team is based on voluntary contributions from the OpenStack community. You can contact the HA community directly in the #openstack-ha channel on Freenode IRC, or by - sending mail to the openstack-dev or openstack-doc mailing list - with the [HA] prefix in the subject header. + sending mail to the openstack-dev mailing list with the [HA] prefix in + the subject header. - The OpenStack HA community holds `weekly IRC meetings + The OpenStack HA community used to hold `weekly IRC meetings `_ to discuss - a range of topics relating to HA in OpenStack. Everyone interested is - encouraged to attend. The `logs of all previous meetings - `_ are available to read. + a range of topics relating to HA in OpenStack. The + `logs of all past meetings + `_ are still available to + read. Contents ~~~~~~~~