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.
Akihiro 2015-11-24 7:33 GMT+09:00 Lana Brindley <openst...@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[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-i18n mailing list > openstack-i...@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n __________________________________________________________________________ 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