[Contributor Guide] Documentation bugs
Reworks and converts the Understanding doc bugs section of the HowTo wikipage: https://wiki.openstack.org/wiki/Documentation/HowTo Change-Id: I3a847097d8b9dae8691a865d892302e7447562a6 Implements: blueprint docs-contributor-guide
This commit is contained in:
Maria Zlatkova
163
doc/contributor-guide/source/doc-bugs.rst
Normal file
163
doc/contributor-guide/source/doc-bugs.rst
Normal file
@@ -0,0 +1,163 @@
|
|||||||
|
|
||||||
|
.. _doc_bugs:
|
||||||
|
|
||||||
|
==================
|
||||||
|
Documentation bugs
|
||||||
|
==================
|
||||||
|
|
||||||
|
The Documentation team tracks all its work through bugs. This section includes
|
||||||
|
the detailed overview of documentation bugs specifics.
|
||||||
|
|
||||||
|
Bugs differ depending on:
|
||||||
|
|
||||||
|
* The way they are filed:
|
||||||
|
|
||||||
|
* Manually
|
||||||
|
* Automatically (through the DocImpact flag)
|
||||||
|
|
||||||
|
* The required changes:
|
||||||
|
|
||||||
|
* Fix spelling errors or formatting
|
||||||
|
* Update exising content
|
||||||
|
* Add new content
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
To work on documentation bugs, join the openstack-doc-bugs team on
|
||||||
|
Launchpad. For more information, see :ref:`first_timers_quickstart`.
|
||||||
|
|
||||||
|
Go through the triaging process and look for possible duplicate bugs
|
||||||
|
before working on a bug. Do not work on a documentation bug until it is set to
|
||||||
|
`Confirmed`. Ideally, another person has to 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`_.
|
||||||
|
|
||||||
|
**DocImpact**
|
||||||
|
|
||||||
|
When adding code that affects documentation (for example, to add a new
|
||||||
|
parameter), the developer adds a DocImpact flag. This flag automatically
|
||||||
|
files a bug in the system explaining what needs to be done. For more
|
||||||
|
information, see: `Documentation/DocImpact`_.
|
||||||
|
|
||||||
|
Launchpad projects and repositories
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The Documentation team uses two projects for tracking documentation bugs
|
||||||
|
across OpenStack:
|
||||||
|
|
||||||
|
* Launchpad bug area `openstack-manuals`_ is the default one for doc bugs and
|
||||||
|
should be used for docs sourced from these repositories:
|
||||||
|
|
||||||
|
* clouddocs-maven-plugin
|
||||||
|
* ha-guide
|
||||||
|
* openstackdocstheme
|
||||||
|
* openstack-doc-tools
|
||||||
|
* openstack-manuals
|
||||||
|
* operations-guide
|
||||||
|
* security-doc
|
||||||
|
|
||||||
|
* Launchpad bug area `openstack-api-site`_ is used for the api-site API
|
||||||
|
repository.
|
||||||
|
|
||||||
|
Doc bug triaging guidelines
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Bug triaging is the process of reviewing new bugs, verifying whether a bug is
|
||||||
|
valid or not, and gathering more information about it. Before being triaged,
|
||||||
|
all the new bugs have the status New, and importance Undecided. Here are the
|
||||||
|
definitions for available options for Status and Importance columns of any bug.
|
||||||
|
|
||||||
|
**Status:**
|
||||||
|
|
||||||
|
* **New** - Recently logged by a non-triaging person.
|
||||||
|
* **Incomplete** - Needs additional information before it can be triaged.
|
||||||
|
* **Opinion** - Does not fit the project but can still be discussed.
|
||||||
|
* **Invalid** - Not an issue for docs.
|
||||||
|
* **Won't Fix** - Documentation fixes won't fix the issue.
|
||||||
|
* **Confirmed** - Acknowledged that it is a documentation bug.
|
||||||
|
* **Triaged** - Comments in the bug indicate its scope and amount of work to
|
||||||
|
be done.
|
||||||
|
* **In Progress** - Someone is working on it.
|
||||||
|
* **Fix Committed** - A fix is in the repository; Gerrit sets this
|
||||||
|
automatically. Do not set this manually.
|
||||||
|
* **Fix Released** - A fix is published to the site.
|
||||||
|
|
||||||
|
.. Note::
|
||||||
|
|
||||||
|
Since all documentation is released directly on docs.openstack.org, the
|
||||||
|
"Fix Committed" status is deprecated. If a patch contains the line
|
||||||
|
"Closes-Bug: #12345" (see git commit messages for details), our CI
|
||||||
|
infrastructure automatically sets the bug to "Fix Released" once the patch
|
||||||
|
is merged.
|
||||||
|
|
||||||
|
**Importance:**
|
||||||
|
|
||||||
|
* **Critical** - Data will be lost if this bug stays in; or it is so bad that
|
||||||
|
we are better off fixing it than dealing with all the incoming questions
|
||||||
|
about it. Also items on the website itself that prevent access are Critical
|
||||||
|
doc bugs.
|
||||||
|
* **High** - Definitely need docs about this or a fix to current docs; docs are
|
||||||
|
incomplete without this. Work on these first if possible.
|
||||||
|
* **Medium** - Need docs about this within a six-month release timeframe.
|
||||||
|
* **Low** - Docs are fine without this but could be enhanced by fixing this
|
||||||
|
bug.
|
||||||
|
* **Wishlist** - Not really a bug but a welcome change. If something is wrong
|
||||||
|
with the doc, mark the bug as Low rather than Wishlist.
|
||||||
|
* **Undecided** - Recently logged by a non-triaging person or requires more
|
||||||
|
research before deciding its importance.
|
||||||
|
|
||||||
|
Tags for doc bugs
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Depending on the area a bug affects, it has one or more tags. For example:
|
||||||
|
|
||||||
|
* **low-hanging-fruit** for documentaion 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
|
||||||
|
guides.
|
||||||
|
|
||||||
|
* **doc-builds** for documentation bugs that are in the documentation build
|
||||||
|
tool chain, such as the Sphinx theme, openstackdocstheme.
|
||||||
|
|
||||||
|
Doc bug categories
|
||||||
|
------------------
|
||||||
|
|
||||||
|
To help with bug fixing, use these quick links to pick a certain subset of
|
||||||
|
bugs:
|
||||||
|
|
||||||
|
* `list of all documentation bugs`_
|
||||||
|
* `list of all API site bugs`_
|
||||||
|
* `low hanging fruit documentation bugs`_
|
||||||
|
* `nova-related documentation bugs`_
|
||||||
|
* `keystone-related documentation bugs`_
|
||||||
|
* `neutron-related documentation bugs`_
|
||||||
|
* `swift-related documentation bugs`_
|
||||||
|
* `glance-related documentation bugs`_
|
||||||
|
* `cinder-related documentation bugs`_
|
||||||
|
* `xen-related documentation bugs`_
|
||||||
|
|
||||||
|
|
||||||
|
.. Links
|
||||||
|
|
||||||
|
.. _`the aggregated list of documentation bugs from all OpenStack projects`: https://bugs.launchpad.net/openstack/+bugs?field.tag=documentation
|
||||||
|
|
||||||
|
.. _`Documentation/DocImpact`: https://wiki.openstack.org/wiki/Documentation/DocImpact
|
||||||
|
|
||||||
|
.. _`list of all documentation bugs`: https://bugs.launchpad.net/openstack-manuals
|
||||||
|
.. _`list of all API site bugs`: https://bugs.launchpad.net/openstack-api-site
|
||||||
|
|
||||||
|
.. _`openstack-manuals`: https://bugs.launchpad.net/openstack-manuals
|
||||||
|
.. _`openstack-api-site`: https://bugs.launchpad.net/openstack-api-site
|
||||||
|
|
||||||
|
.. _`low hanging fruit documentation bugs`: https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=low-hanging-fruit
|
||||||
|
.. _`nova-related documentation bugs`: https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=nova
|
||||||
|
.. _`keystone-related documentation bugs`: https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=keystone
|
||||||
|
.. _`neutron-related documentation bugs`: https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=neutron
|
||||||
|
.. _`swift-related documentation bugs`: https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=swift
|
||||||
|
.. _`glance-related documentation bugs`: https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=glance
|
||||||
|
.. _`cinder-related documentation bugs`: https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=cinder
|
||||||
|
.. _`xen-related documentation bugs`: https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=xen
|
||||||
@@ -23,6 +23,7 @@ Contents
|
|||||||
docs_builds.rst
|
docs_builds.rst
|
||||||
writing-style.rst
|
writing-style.rst
|
||||||
json_conventions.rst
|
json_conventions.rst
|
||||||
|
doc-bugs.rst
|
||||||
|
|
||||||
|
|
||||||
Search in this guide
|
Search in this guide
|
||||||
|
|||||||
Reference in New Issue
Block a user