Open Stack

Excerpts from Lana Brindley's message of 2016-01-11 14:31:17 +1000:
> 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

Can you clarify what you're worried about here? The point of the
new tool is that once the note is added to the patch with the code,
there is no more manual work to do to publish it.

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

There was a period of time early on where we were still rolling out the
tool that notes may not have been written. Each project team was
supposed to go back and review commits made prior to turning reno on to
see if they needed notes, and to commit them separately. Has that been
done here?

Perhaps one way to take advantage of both tools is to have the DocImpact
validation look inside the commit and require a release notes file? That
way the reviewable portion of the commit is not in the message, but we
can still require some description of why DocImpact was added.

Doug

> 
> My experience would indicate that many, many DocImpact bugs are really not worthy of relnotes.
> 
> > 
> >>>
> >>> Bugs and relnotes are two very different things.
> 
> 
> L
> 
>