5.1 KiB
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
DocImpact
so 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 Guide
The 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
DocImpact
bugs, 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. DocImpact
doesn'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
DocImpact
flag 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)