Merge "[contrib-guide] Updating with bug triage liaison info"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
3f1b927f60
@ -1,72 +1,12 @@
|
|||||||
.. _doc_bugs:
|
.. _doc_bugs:
|
||||||
|
|
||||||
============================
|
==================
|
||||||
Reporting documentation bugs
|
Documentation bugs
|
||||||
============================
|
==================
|
||||||
|
|
||||||
The Documentation team tracks all its work through bugs. This section includes
|
The Documentation team tracks all its work through bugs. This section includes
|
||||||
the detailed overview of documentation bugs specifics.
|
the detailed overview of documentation bugs specifics.
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
To work on documentation bugs, join the openstack-doc-bugs team on
|
|
||||||
Launchpad. For more information, see :ref:`first_timers`.
|
|
||||||
|
|
||||||
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
|
|
||||||
<https://bugs.launchpad.net/openstack/+bugs?field.tag=documentation>`_.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
**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
|
|
||||||
<https://wiki.openstack.org/wiki/Documentation/DocImpact>`_.
|
|
||||||
|
|
||||||
Launchpad projects and repositories
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The Documentation team uses the following projects for tracking documentation
|
The Documentation team uses the following projects for tracking documentation
|
||||||
bugs across OpenStack:
|
bugs across OpenStack:
|
||||||
|
|
||||||
@ -83,11 +23,91 @@ bugs across OpenStack:
|
|||||||
* `openstack-doc-tools <https://bugs.launchpad.net/openstack-doc-tools>`_ is
|
* `openstack-doc-tools <https://bugs.launchpad.net/openstack-doc-tools>`_ is
|
||||||
used for the doc-tools and openstackdocstheme repositories.
|
used for the doc-tools and openstackdocstheme repositories.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
.. _doc_bugs_triaging:
|
doc-impact.rst
|
||||||
|
|
||||||
|
Bug triage liaison
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The documentation team assigns bug triage liaisons to ensure all bugs reported
|
||||||
|
against OpenStack manuals 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.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Read this page in full. Keep this document in mind at all times as it
|
||||||
|
describes the duties of the liaison and how to triage bugs. In particular,
|
||||||
|
it describes how to set bug importance, and how to select bug tags.
|
||||||
|
|
||||||
|
#. Before you begin to work on documentation bugs, you must join the
|
||||||
|
openstack-doc-bugs team on Launchpad. For more information,
|
||||||
|
see :ref:`first_timers`.
|
||||||
|
|
||||||
|
#. Sign up for openstack-manuals emails from Launchpad if you have not already:
|
||||||
|
|
||||||
|
#. 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
|
||||||
|
like :guilabel:`Docs Bugs`. You can choose
|
||||||
|
either option or how much mail you get, but keep in mind that getting
|
||||||
|
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).
|
||||||
|
|
||||||
|
#. View your scheduled week 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.
|
||||||
|
|
||||||
|
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 the reported bug affects the ReST API, tools, openstackdocstheme, or
|
||||||
|
the Security Guide, add the relevant project to the affected
|
||||||
|
projects and remove ``openstack-manuals``.
|
||||||
|
For example, if the bug affects the ReST API, file a bug in
|
||||||
|
``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``.
|
||||||
|
|
||||||
|
* Set the bug to ``Invalid`` if it is a request for support or a
|
||||||
|
troubleshooting request.
|
||||||
|
|
||||||
|
* Check if a similar bug was filed before. You may also check
|
||||||
|
already verified bugs to see if the bug has been reported. If so, mark it as
|
||||||
|
a duplicate of the previous bug.
|
||||||
|
|
||||||
|
* Verify if the bug meets the requirements of a good bug report by checking
|
||||||
|
that the guidelines or checklist has been followed.
|
||||||
|
|
||||||
|
* Omitted information is still acceptable if the issue is clear. Use your good
|
||||||
|
judgment and your experience and consult another core member or the PTL if in
|
||||||
|
doubt. If the bug report requires more context, mark the bug as
|
||||||
|
``Incomplete``, point the submitter to this document.
|
||||||
|
|
||||||
|
.. _guidelines:
|
||||||
|
|
||||||
Doc bug triaging guidelines
|
Doc bug triaging guidelines
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
---------------------------
|
||||||
|
|
||||||
Bug triaging is the process of reviewing new bugs, verifying whether a bug is
|
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,
|
valid or not, and gathering more information about it. Before being triaged,
|
||||||
@ -147,8 +167,24 @@ Depending on the area a bug affects, it has one or more tags. For example:
|
|||||||
* **infra**, **theme** for documentation bugs that are in the documentation
|
* **infra**, **theme** for documentation bugs that are in the documentation
|
||||||
build tool chain.
|
build tool chain.
|
||||||
|
|
||||||
|
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
|
||||||
|
<https://bugs.launchpad.net/openstack-manuals/+subscriptions>`_:
|
||||||
|
|
||||||
|
#. Select :guilabel:`Add a subscription`.
|
||||||
|
#. Select the option to receive mail for bugs affecting the project
|
||||||
|
that :guilabel:`are added or changed in any way`.
|
||||||
|
#. Check the :guilabel:`Bugs must match this filter` checkbox.
|
||||||
|
#. Select the :guilabel:`Tags` subsection.
|
||||||
|
#. Populate the tag(s) you want to track.
|
||||||
|
#. Create the subscription.
|
||||||
|
|
||||||
Bugs for third-party drivers
|
Bugs for third-party drivers
|
||||||
----------------------------
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Bugs to update tables for the configuration references use the tag
|
Bugs to update tables for the configuration references use the tag
|
||||||
**autogenerate-config-docs**.
|
**autogenerate-config-docs**.
|
||||||
@ -165,31 +201,49 @@ committer of the change that triggered the bug report, mark it as
|
|||||||
specification and handle it since the documentation team will not
|
specification and handle it since the documentation team will not
|
||||||
document third-party drivers.
|
document third-party drivers.
|
||||||
|
|
||||||
Doc bug categories
|
Filing a bug
|
||||||
------------------
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
To help with bug fixing, use these quick links to pick a certain subset of
|
Bugs differ depending on:
|
||||||
bugs:
|
|
||||||
|
|
||||||
* `list of all documentation bugs
|
* The way they are filed:
|
||||||
<https://bugs.launchpad.net/openstack-manuals>`_
|
|
||||||
* `list of all API site bugs
|
|
||||||
<https://bugs.launchpad.net/openstack-api-site>`_
|
|
||||||
* `low hanging fruit documentation bugs
|
|
||||||
<https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=low-hanging-fruit>`_
|
|
||||||
|
|
||||||
Tracking bugs by tag
|
* Manually
|
||||||
--------------------
|
* Automatically (through the DocImpact flag)
|
||||||
|
|
||||||
If you need to regularly track activity relating to particular tags,
|
* The required changes:
|
||||||
you can set up email subscriptions by visiting `the subscriptions page
|
|
||||||
of the launchpad project
|
|
||||||
<https://bugs.launchpad.net/openstack-manuals/+subscriptions>`_:
|
|
||||||
|
|
||||||
1. Select :guilabel:`Add a subscription`.
|
* Fix spelling errors or formatting
|
||||||
2. Select the option to receive mail for bugs affecting the project
|
* Update existing content
|
||||||
that :guilabel:`are added or changed in any way`.
|
* Add new content
|
||||||
3. Check the :guilabel:`Bugs must match this filter` checkbox.
|
|
||||||
4. Select the :guilabel:`Tags` subsection.
|
.. important::
|
||||||
5. Populate the tag(s) you want to track.
|
|
||||||
6. Create the subscription.
|
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>`_.
|
||||||
|
|||||||
86
doc/contributor-guide/source/doc-impact.rst
Normal file
86
doc/contributor-guide/source/doc-impact.rst
Normal file
@ -0,0 +1,86 @@
|
|||||||
|
=========
|
||||||
|
DocImpact
|
||||||
|
=========
|
||||||
|
|
||||||
|
When adding code that affects documentation (for example, to add a new
|
||||||
|
parameter), the developer adds a DocImpact flag.
|
||||||
|
|
||||||
|
Using the DocImpact flag in a commit message
|
||||||
|
--------------------------------------------
|
||||||
|
|
||||||
|
In any OpenStack project, you can add a ``DocImpact`` flag in a commit message
|
||||||
|
to help identify any bugs that require documentation to be written
|
||||||
|
in the OpenStack manuals project.
|
||||||
|
|
||||||
|
This method offers notification and tracking of the possible impact to
|
||||||
|
documentation due to the patch. If your commit has an impact on
|
||||||
|
documentation, for example an added, altered, or removed command line option,
|
||||||
|
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.
|
||||||
|
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
|
||||||
|
notification comes to the list.
|
||||||
|
|
||||||
|
#. Create a new doc bug in either ``openstack-manuals`` or
|
||||||
|
``openstack-api-site``.
|
||||||
|
In the bug:
|
||||||
|
|
||||||
|
#. In the title, put ``newton`` or ``ocata`` depending on the release the
|
||||||
|
patch affects.
|
||||||
|
#. Copy and paste the `<review.openstack.org>`_ link in the bug description.
|
||||||
|
#. Describe the documentation that is affected if the code patch lands in
|
||||||
|
the bug description.
|
||||||
|
#. Keep the doc bug set to ``New`` until the code patch is merged.
|
||||||
|
|
||||||
|
#. 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.
|
||||||
|
|
||||||
|
Writing good commit messages for DocImpact
|
||||||
|
------------------------------------------
|
||||||
|
|
||||||
|
Because the entire commit message is included in the logged bug, try to put
|
||||||
|
as much information as you can into the commit message about which doc audience
|
||||||
|
is affected by the change or enhancement, what the change is and why it
|
||||||
|
matters.
|
||||||
|
Answer the following questions when writing the commit message:
|
||||||
|
|
||||||
|
* Who would use the feature?
|
||||||
|
|
||||||
|
* Why use the feature?
|
||||||
|
|
||||||
|
* What is the exact usage for the feature? If it's an API change,
|
||||||
|
give example requests and responses.
|
||||||
|
|
||||||
|
* Does the feature also have permissions/policies attached? If so, what are
|
||||||
|
the requirements?
|
||||||
|
|
||||||
|
If it is a configuration option change, our automation will pick it up.
|
||||||
|
However, we do request for individually filed bugs outside of the automated
|
||||||
|
generation.
|
||||||
|
|
||||||
|
If it is a CLI change, we also have automation that picks up the help text,
|
||||||
|
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:
|
||||||
|
|
||||||
|
.. code-block: yaml
|
||||||
|
|
||||||
|
- project: stackforge/project-name
|
||||||
|
description: Latest and greatest cloud stuff.
|
||||||
|
upstream: git://github.com/awesumsauce/project-name.git
|
||||||
|
docimpact-group: Project
|
||||||
Loading…
x
Reference in New Issue
Block a user