Open Stack

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 <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[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-i18n at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n