[openstack-dev] [Openstack-i18n] DocImpact Changes

Andreas Jaeger aj at suse.com
Wed Nov 25 14:41:42 UTC 2015


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-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/


-- 
  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




More information about the OpenStack-dev mailing list