The Documentation team tracks all its work through bugs. This section includes the detailed overview of documentation bugs specifics.
To work on documentation bugs, join the openstack-doc-bugs team on Launchpad. For more information, see 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.
Bugs differ depending on:
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.
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.
The Documentation team uses the following projects for tracking documentation bugs across OpenStack:
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.
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.
Bugs to update tables for the configuration references use the tag autogenerate-config-docs.
For updates of specific sections or adding of new drivers, follow the specification Proprietary driver docs in openstack-manuals and assign the bug to the contact person that is mentioned on the Vendor driver page. If this is a new driver with no documentation yet, assign the bug to the 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.
To help with bug fixing, use these quick links to pick a certain subset of bugs:
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: