From bc80313b5a5e24aa086e5a904146e34cebb25b85 Mon Sep 17 00:00:00 2001 From: Alexandra Settle Date: Tue, 28 Feb 2017 14:11:59 +0000 Subject: [PATCH] [contrib-guide] Updating with bug triage liaison info Also moves docimpact content from wiki to contrib guide Change-Id: I82cd2165747d8c0ffa1d1011b9f6e8a32cfea861 --- doc/contributor-guide/source/doc-bugs.rst | 232 ++++++++++++-------- doc/contributor-guide/source/doc-impact.rst | 86 ++++++++ 2 files changed, 229 insertions(+), 89 deletions(-) create mode 100644 doc/contributor-guide/source/doc-impact.rst diff --git a/doc/contributor-guide/source/doc-bugs.rst b/doc/contributor-guide/source/doc-bugs.rst index e195468d5a..d0b6a2d4ed 100644 --- a/doc/contributor-guide/source/doc-bugs.rst +++ b/doc/contributor-guide/source/doc-bugs.rst @@ -1,72 +1,12 @@ .. _doc_bugs: -============================ -Reporting documentation bugs -============================ +================== +Documentation bugs +================== The Documentation team tracks all its work through bugs. This section includes 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 -`_. - -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. - -**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 the following projects for tracking documentation bugs across OpenStack: @@ -83,11 +23,91 @@ bugs across OpenStack: * `openstack-doc-tools `_ is 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 `_ + 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- 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, @@ -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 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 +`_: + +#. 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 to update tables for the configuration references use the tag **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 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: +Bugs differ depending on: -* `list of all documentation bugs - `_ -* `list of all API site bugs - `_ -* `low hanging fruit documentation bugs - `_ +* The way they are filed: -Tracking bugs by tag --------------------- + * Manually + * Automatically (through the DocImpact flag) -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 -`_: +* The required changes: -1. Select :guilabel:`Add a subscription`. -2. Select the option to receive mail for bugs affecting the project - that :guilabel:`are added or changed in any way`. -3. Check the :guilabel:`Bugs must match this filter` checkbox. -4. Select the :guilabel:`Tags` subsection. -5. Populate the tag(s) you want to track. -6. Create the subscription. + * 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/contributor-guide/source/doc-impact.rst b/doc/contributor-guide/source/doc-impact.rst new file mode 100644 index 0000000000..1c6ac02492 --- /dev/null +++ b/doc/contributor-guide/source/doc-impact.rst @@ -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 ``_ 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