-----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[1], 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[2].
* 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 [3] and [4].
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.
Thanks,
Lana
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
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
iQEcBAEBCAAGBQJWU5Q0AAoJELppzVb4+KUyYz4H/j+iAG5x2iRiNbJMBgxm5Qb5
tvxzlOePHZa6VQKj1gYrp8wnBFab0CsNDt/U03D8H9D6No2hqz5qvFgOuMDXIOkS
DXG+2RDD8xKMRS42t70mNtJu2oPl+9BWIre+Qyvjd7heicGd+lN/mqAvmwVV3tKB
fwJl3iLrlSpwwsyunzR3LxGxzVfHUroRdFv11iQGQZNJYbS9DfOLsz66e5JBTZPh
ZoCK8VAlEionaL8ExppoMPQOwpU0oYMWSjM2HGxlc/RDrNEz7HWfXl36nxqfw/mO
q8Op0p5cn5UW4fYv/9Ufbw6k0JRgwODCwzSEzJ73gmOJpBrcTEdZKocnGDSdtYA=
=CCIn
-----END PGP SIGNATURE-----
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
