openstack/openstack-manuals
Code Issues Proposed changes

Update docs for documentation bugs

Browse Source 
Make them less specific to openstack-manuals.
Remove occurrences of the openstack-docs ML.

Change-Id: I93cdf4e24863412b64305211ee88e6eaf60409e4
This commit is contained in:
Petr Kovar 2018-01-23 18:32:45 +01:00
parent 199e68f895
commit 99c77b1b6b
4 changed files with 113 additions and 116 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
doc/doc-contrib-guide/source/doc-bugs.rst
View File

@ -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 <https://bugs.launchpad.net/openstack-manuals>`_ is the
default area for doc bugs in the openstack-manuals repository.
* `openstack-api-site <https://bugs.launchpad.net/openstack-api-site>`_ is used
for the api-site API repository.
* `openstack-contributor-guide <https://bugs.launchpad.net/openstack-contributor-guide>`_
is used for the contributor-guide repository.
* `OpenStack Security Guide Documentation
<https://bugs.launchpad.net/ossp-security-documentation>`_ is used for the
security-doc repository.
* `openstack-api-site <https://bugs.launchpad.net/openstack-api-site>`_ is used
for the api-site API repository.
* `openstack-doc-tools <https://bugs.launchpad.net/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 <https://ask.openstack.org/en/questions/>`_
or the OpenStack mailing list.
For more information about the relevant IRC channels, see the
`OpenStack IRC wiki <https://wiki.openstack.org/wiki/IRC>`_.
For more information about the OpenStack mailing list, see the
`Mailing lists wiki <https://wiki.openstack.org/wiki/Mailing_Lists>`_.
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
<https://bugs.launchpad.net/openstack/+bugs?field.tag=documentation>`_.
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
<https://bugs.launchpad.net/openstack-manuals>`_.
#. 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 <https://wiki.openstack.org/wiki/Documentation/SpecialityTeams#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
<https://wiki.openstack.org/wiki/Documentation/SpecialityTeams#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
<https://bugs.launchpad.net/openstack-manuals/+subscriptions>`_:
#. 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 <https://ask.openstack.org/en/questions/>`_
or the OpenStack mailing list.
For more information about the relevant IRC channels, see the
`OpenStack IRC wiki <https://wiki.openstack.org/wiki/IRC>`_.
For more information about the OpenStack mailing list, see the
`Mailing lists wiki <https://wiki.openstack.org/wiki/Mailing_Lists>`_.
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
<https://bugs.launchpad.net/openstack/+bugs?field.tag=documentation>`_.

17
doc/doc-contrib-guide/source/doc-impact.rst
View File

@ -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
<https://git.openstack.org/cgit/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.

36
doc/doc-contrib-guide/source/topic-tags.rst
View File

@ -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

13
doc/ha-guide/source/index.rst
View File

@ -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
<https://wiki.openstack.org/wiki/Meetings/HATeamMeeting>`_ to discuss
a range of topics relating to HA in OpenStack. Everyone interested is
encouraged to attend. The `logs of all previous meetings
<http://eavesdrop.openstack.org/meetings/ha/>`_ are available to read.
a range of topics relating to HA in OpenStack. The
`logs of all past meetings
<http://eavesdrop.openstack.org/meetings/ha/>`_ are still available to
read.
Contents
~~~~~~~~