Using the DocImpact Flag in a Commit Message
In any OpenStack project, you can add a DocImpact flag in a commit message to automatically log a bug in the openstack-manuals project in Launchpad. The bug is not set to "Confirmed" until the patch merges. This method offers notification and tracking of the possible impact to documentation due to the patch. If your commit could have an impact on documentation - be it an added/altered/removed command line option, a deprecated or new feature, a caveat, if you've written docs in the patch, or if you're just not sure, just add "DocImpact" to a line in your commit message.
This sends the doc team an email so we can triage. It doesn't guarantee docs will be written, but at least it gives us visibility of the changes. You can also use it as a reminder to yourself to write docs for the feature later, that's okay too. With over 500 contributors to the code base and a handful of writers, there's always doc work to be done.
If you are a doc contributor, these are the steps we take once a DocImpact notification comes to the list.
1. Create a new doc bug in either openstack-manuals or openstack-api-site. In the bug:
- In the title, put "grizzly" or "havana" depending on the release the patch will land in.
- 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.
2. Continue to check on the patch and change the status to "Confirmed" once merged.
3. Use the information in the Doc Bug Triaging Guidelines section to set priority once it lands.
Third-Party DocImpact settings
By default DocImpact tag creates bugs in openstack-manuals Launchpad project. To change this behaviour the docimpact-group option in projects.yaml can be used. For example, if you set project like this::
- project: stackforge/project-name description: Latest and greatest cloud stuff. upstream: git://github.com/awesumsauce/project-name.git docimpact-group: Project
documentation bugs will be created in http://launchpad.net/Project