[openstack-dev] [doc] DocImpact vs. reno

Lana Brindley openstack at lanabrindley.com
Mon Jan 11 04:31:17 UTC 2016

Hash: SHA256

On 09/01/16 14:07, Tom Fifield wrote:
> On 08/01/16 21:15, Sean Dague wrote:
>> On 01/07/2016 06:21 PM, Lana Brindley wrote:
>>>> On 7 Jan 2016, at 2:09 AM, Sean Dague <sean at dague.net> wrote:
>>>> On 01/06/2016 09:02 AM, Jeremy Stanley wrote:
>>>>> On 2016-01-06 07:52:48 -0500 (-0500), Sean Dague wrote:
>>>>> [...]
>>>>>> I think auto openning against a project, and shuffling it to
>>>>>> manuals manually (with details added by humans) would be fine.
>>>>>> It's not clear to me why a new job was required for that.
>>>>> The new check job was simply a requirement of the Docs team, since
>>>>> they were having trouble triaging auto-generated bugs they were
>>>>> receiving and wanted to enforce the inclusion of some expository
>>>>> metadata.
>>>> Sure, but if that triage is put back on the Nova team, that seems fine.
>>> So you’re thinking we should make all docimpact bugs go to the project bug queue? Even for defcore?
>> Yes, because then it would be the responsibility of the project team to
>> ensure there is enough info before passing it onto the docs team.

I'm willing to try this, if the defcore teams approve.

>>>> It also doesn't make sense to me there would be a DocImpact change that
>>>> wouldn't also have a reno section. The reason someone thinks that a
>>>> change needs reflection in the manual is that it adds/removes/changes a
>>>> feature that would also show up in release notes. Perhaps my imagination
>>>> isn't sufficient to come up with a scenario where DocImpact is valid,
>>>> but we wouldn't have content in one of those sections.
>>> I can think of plenty. What about where a command is changed slightly? Or an output is formatted differently? Or where flags have been removed, or default values changed, or ….
>> Nearly all of those changes have been triggering release notes at this
>> point. They are all changes the user needs to adapt to because they
>> potentially impact compatibility.

Wow. That'll make the release notes process painful this round ... o.O

> Would love it to be the case, but I don't think that's correct. Or if it's supposed to be correct, it hasn't been well communicated :)
> Few random reviews from the DocImpact queue that didn't have relnotes:
> https://review.openstack.org/#/c/180202/
> https://review.openstack.org/#/c/249814/
> https://review.openstack.org/#/c/250818/
> https://review.openstack.org/#/c/230983/
> Didn't really look closely into these - would encourage someone with a bit more time to do so, but the fact that these were so trivial to eke out means that "nearly all" is almost certainly a bad assumption.

My experience would indicate that many, many DocImpact bugs are really not worthy of relnotes.

>>> Bugs and relnotes are two very different things.


- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/


More information about the OpenStack-dev mailing list