[Openstack-i18n] DocImpact Changes
amotoki at gmail.com
Tue Nov 24 06:07:04 UTC 2015
it sounds a good idea in general.
One question is how each project team should handle DocImpact bugs
filed in their own project.
It will be a part of "Plan and implement an education campaign"
mentioned in the docs spec.
I think some guidance will be needed. One usual question will be which
guide(s) needs to be updated?
openstack-manuals now have a lot of manuals and most developers are
not aware of all of them.
2015-11-24 7:33 GMT+09:00 Lana Brindley <openstack at lanabrindley.com>:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
> Hi everyone,
> The DocImpact flag was implemented back in Havana to make it easier for developers to notify the documentation team when a patch might cause a change in the docs. This has had an overwhelming response, resulting in a huge amount of technical debt for the docs team, so we've been working on a plan to change how DocImpact works. This way, instead of just creating a lot of noise, it will hopefully go back to being a useful tool. This is written in more detail in our spec, but this email attempts to hit the highlights for you.
> TL;DR: In the future, you will need to add a description whenever you add a DocImpact flag in your commit message.
> Right now, if you create a patch and include 'DocImpact' in the commit message, Infra raises a bug in either the openstack-manuals queue, or (for some projects) your own project queue. DocImpact is capable of handling a description field, but this is rarely used. Instead, docs writers are having to dig through your patch to determine what (if any) change is required.
> What we are now implementing has two main facets:
> * The DocImpact flag can only be used if it includes a description. A Jenkins job will test for this, and if you include DocImpact without a description, the job will fail. The description can be a short note about what needs changing in the docs, a link to a gist or etherpad with more information, or a note about the location of incorrect docs. There are specific examples in the spec.
> * Only Nova, Swift, Glance, Keystone, and Cinder will have DocImpact bugs created in the openstack-manuals queue. All other projects will have DocImpact bugs raised in their own queue. This is handled in  and .
> This will hopefully reduce the volume of DocImpact bugs being created in the openstack-manuals queue, and also improve the quality of the bugs that are created.
> I know there is a fair amount of confusion over DocImpact already, so I'm more than happy to field questions on this.
> 1: http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpact.html
> 2: http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpact.html#examples
> 3: https://review.openstack.org/#/c/248515/
> 4: https://review.openstack.org/#/c/248549/
> - --
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2
> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
> -----END PGP SIGNATURE-----
> Openstack-i18n mailing list
> Openstack-i18n at lists.openstack.org
More information about the Openstack-i18n