-----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-docimpac... 2: http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpac... 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-----
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@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-docimpac... 2: http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpac... 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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi Akihiro, Judging by most of the bugs we see in the openstack-manuals queue, the bugs that will be raised in projects' own queues will usually be against their own developer documentation. In the rare instance that that isn't the case, and it needs to come into one of the openstack-manuals docs, then we are happy to discuss the issue with the person who raised the bug and, possibly, take the bug in our queue to be fixed. To be clear: just because DocImpact raises a bug in a projects' queue, doesn't mean docs aren't available to help fix it. We're always here for you to ask questions about docs bugs, even if those bugs are in your repo and your developer documentation. I hope that answers the question. Thanks, Lana On 24/11/15 16:07, Akihiro Motoki wrote:
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@lanabrindley.com>: 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-docimpac... 2: http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpac... 3: https://review.openstack.org/#/c/248515/ 4: https://review.openstack.org/#/c/248549/
_______________________________________________ Openstack-i18n mailing list Openstack-i18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
- -- 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/ iQEcBAEBCAAGBQJWVNJrAAoJELppzVb4+KUy0ggIALEv0MaKfubZZ4wpyUZnWBsb QqTTufVJZ8o/p6CanDkFl4EnyaAtsmoe/hYIlmqDMxWCDichIB829G11WjfHZz/H g6tsUar640bHs2XSh8MTtkTYY5wX2MIL+2FMqIioCSn7rGc/AXBdDRhqp8HYJBoX yP8PM6uSYQIEzYfmwQ4McZaRmXfPfqnvB+AWcmf96/nwYvndSk+WrELR6vQmhoIf mWKkdpwtp6sNJ0DYkxwhWjEE5e6bbQ2mnYz+gKGsptoTl8GwxiGWJjakPn6fzKhr CJ+ofXtOp2PNS4GzQiJrt6sHKgLiXGGQ0iCGn2BqPZqWLjKenWPGmeg2Ybgm6Y8= =4dRC -----END PGP SIGNATURE-----
These changes have merged now, Andreas On 2015-11-23 23:33, Lana Brindley wrote:
-----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-docimpac... 2: http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpac... 3: https://review.openstack.org/#/c/248515/ 4: https://review.openstack.org/#/c/248549/
-- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
participants (3)
-
Akihiro Motoki
-
Andreas Jaeger
-
Lana Brindley