Jump to: navigation, search

Difference between revisions of "Documentation/DocImpact"

(Created page with "=== Using the DocImpact Flag in a Commit Message === In any OpenStack project, you can add a DocImpact flag in a commit message to send an email to the openstack-docs mailing ...")
 
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
=== Using the DocImpact Flag in a Commit Message ===
 
=== Using the DocImpact Flag in a Commit Message ===
−
In any OpenStack project, you can add a DocImpact flag in a commit message to send an email to the openstack-docs mailing list notifying them 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 commandline 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.
+
In any OpenStack project, you can add a DocImpact flag in a commit message to automatically log a bug in a specified project in Launchpad. The bug is not set to "Confirmed" until the patch merges. The entire commit message is included in the bug.  
  
−
This sends the doc team an email so we can triage. It doesn't guarantee docs will
+
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.
−
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.
+
 
 +
This creates a Launchpad bug for the project indicated in the gerrit/projects.yaml file in the openstack/project-config repository. It doesn't guarantee docs 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. With over 2000 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.  
 
If you are a doc contributor, these are the steps we take once a DocImpact notification comes to the list.  
Line 16: Line 17:
  
 
3. Use the information in the Doc Bug Triaging Guidelines section to set priority once it lands.
 
3. Use the information in the Doc Bug Triaging 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, why it matters, and so on.
 +
 +
* 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 but we would still want a bug to track with. If it's a CLI change, we also have automation that picks up the help text, but extra usage information is useful. Read an [http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/ example walkthrough] or look at an existing [https://bugs.launchpad.net/openstack-manuals/+bug/1334674 DocImpact logged bug] that had to be triaged further for more information.
 +
 +
==== Third-Party DocImpact settings ====
 +
 +
By default DocImpact tag creates bugs using the repository name as project in Launchpad.
 +
To change this behaviour the '''docimpact-group''' option in [https://git.openstack.org/cgit/openstack-infra/project-config/tree/gerrit/projects.yaml 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
 +
 +
 +
----
 +
[[Category:Documentation]]

Latest revision as of 17:58, 15 December 2016

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 a specified project in Launchpad. The bug is not set to "Confirmed" until the patch merges. The entire commit message is included in the bug.

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 creates a Launchpad bug for the project indicated in the gerrit/projects.yaml file in the openstack/project-config repository. It doesn't guarantee docs 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. With over 2000 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.

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, why it matters, and so on.

  • 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 but we would still want a bug to track with. If it's a CLI change, we also have automation that picks up the help text, but extra usage information is useful. Read an example walkthrough or look at an existing DocImpact logged bug that had to be triaged further for more information.

Third-Party DocImpact settings

By default 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:: 

- 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


Retrieved from "https://wiki.openstack.org/w/index.php?title=Documentation/DocImpact&oldid=145395"