Review DocImpact¶
https://blueprints.launchpad.net/openstack-manuals/+spec/review-docimpact
The DocImpact script creates a lot of noise on the openstack-manuals bug
list. This is partly a social problem (we need to train contributors to use
the DocImpact flag more thoughtfully), but also partly an automation
problem (we should be considering how the DocImpact flag is used, and the
most efficient automation to achieve the end we require.
Problem description¶
Current workflow: Contributors create a patch, and at commit time they think
“oh yeah, probably there should be some docs about that” and whack in a
DocImpact flag. In other words, there’s not a lot of thought going in
here, it’s just an easy thing to do, they get a warm fuzzy, and there’s an
assumption that the documentation fairy comes along and takes care of things.
In reality, what then happens is some docs triager spends an hour looking at
the patch, searching through the docs, then deciding it has nothing to do with
openstack-manuals. Often, the actual doc impact (if there even is one) is
against docs in the dev repo, not openstack-manuals.
In short, contributors recognise they need docs, and DocImpact is an easy
way to feel like they’re doing something productive to make that happen. What
really happens is that those bugs are largely irrelevant for
openstack-manuals, which puts pressure on our core team to triage them
effectively. To try and get some perspective on the size of the problem, here
are some numbers:
Of the 508 current openstack-manuals bugs, 214 are the result of the DocImpact script. 51 of these are yet to be triaged. Right now, there are 170 patches in-flight with the DocImpact tag. To state the obvious, if all them land, that’s 170 new bugs in our queue.
Proposed change¶
- Adjust
DocImpactso that it cannot be used without a description. Currently, that is an optional thing contributors can do, but it appears that no one uses it. This would mean that rather than typing “DocImpact” and moving on with their lives, contributors must write “DocImpact: Something relevant here”. - A Jenkins job is used to test for the description field in patches. If no description field is found, the Jenkins job will fail.
- Currently, all projects default to create a bug in the openstack-manuals queue. This behaviour will be changed so that all projects default to raising a bug in their own repo, and only the five defcore projects (Nova, Swift, Glance, Keystone, and Cinder) go to the openstack-manuals queue. (Neutron to be added once it becomes defcore, planned for 2016).
- Create an education campaign on the dev mailing list, and possibly other channels, in order to try and encourage contributors to use the flag responsibly.
Examples¶
Some examples of correct DocImpact usage:
Where the documentation needs to be updated:
DocImpact: Update in the Networking section of the Ubuntu Install GuideThe type of documentation required:
DocImpact: Add a description and install info for $NEW_FEATURE.Changes to existing documentation:
DocImpact: Current docs say X, should be Y.Link to a longer piece of documentation (such as OpenStack pastebin, etherpad, or a blog post):
DocImpact: For more info, see http://paste.openstack.org/show/479079/
Alternatives¶
- Have a crack team of docs people (potentially with automation
assistance) going through
DocImpactbugs, cc’ing the original patch authors, triaging the valid ones, moving others into dev repos where necessary, and marking the rest invalid. We could team this with an education campaign on the dev mailing list. - Ditch
DocImpact, and force contributors to create their own docs bugs (and patches). This would mean fewer contributors get on with the job of documentation, but at least what we do get would be well-considered, rather than hastily added to their commit message. DocImpactdoesn’t log a bug at all but rather indicates that the patch contains docs. This style of commit message then aligns with APIImpact, where the API Working Group reviews incoming patches with that tag. This won’t work currently, as we don’t have a good mechanism for searching for the flag (the current docs dashboard doesn’t do this).- Do nothing. Leave the
DocImpactflag the way it is, and slowly drown.
Implementation¶
Assignee(s)¶
Primary assignee:
- Lana Brindley (loquacities)
Other contributors:
- Documentation team
- Infra team
Work Items¶
- Enforce a description field on the DocImpact flag. (Infra)
- Review the projects that can raise DocImpact flags in the openstack-manuals queue. (AJaeger)
- Plan and implement an education campaign. (loquacities)
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.