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

Joshua Hesketh joshua.hesketh at gmail.com
Mon Dec 21 05:33:07 UTC 2015


Hey all,

So I just caught up on this thread and the corresponding scrollback in IRC.

First of all, sorry if this came as a surprise to anybody. As Andreas
pointed out this was highlighted in a number of docs email to this list,
but I understand why they might have been overlooked.

The resource usage was indeed a concern I had in mind in implementing the
DocImpact check. That is why I worked on further improvements to zuul to
only need to run the test on jobs that actually use the DocImpact flag[0].
The job does, however, run in under 2min. So the total burden of boot time
+ 2min isn't overly high. I do completely agree with all the concerns and
that it's not ideal though.

More than happy to have the job reverted or turned off while we discuss
this further. From the discussion in IRC it sounds like there'll be a
little bit of holding off until the new year (and people return from
holidays) but overall there seems to be a desire to use reno to replace
parts of this perhaps making the new job redundant.

Cheers,
Josh

[0]
https://review.openstack.org/#/q/status:open+project:openstack-infra/zuul+branch:master+topic:skip-commit,n,z

On Sat, Dec 19, 2015 at 8:52 AM, Sean Dague <sean at dague.net> wrote:

> On 12/18/2015 02:31 PM, Andreas Jaeger wrote:
> > On 12/18/2015 07:45 PM, Sean Dague wrote:
> >> On 12/18/2015 01:34 PM, Andreas Jaeger wrote:
> >>> On 12/18/2015 07:03 PM, Sean Dague wrote:
> >>>> Recently noticed that a new job ended up on all nova changes that was
> >>>> theoertically processing commit messages for DocImpact. It appears
> >>>> to be
> >>>> part of this spec -
> >>>>
> http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpact.html
> >>>>
> >>>>
> >>>
> >>> Lana talked with John Garbutt about this and announced this also in
> >>> several 'What's up' newsletters like
> >>>
> http://lists.openstack.org/pipermail/openstack-dev/2015-December/081522.html
> >>>
> >>>
> >>>
> >>>> First, a heads up would be good. Nova burns a lot of nodes (i.e. has a
> >>>> lot of patch volume), so this just decreased everyone's CI capacity
> >>>> noticably.
> >>>
> >>> I understand this reasoning and Joshua worked on a superior solution,
> >>> see
> >>>
> https://review.openstack.org/#/q/status:open+project:openstack-infra/zuul+branch:master+topic:skip-commit,n,z
> >>>
> >>>
> >>>
> >>>>
> >>>> Secondly, this all seems like the wrong direction. We've got reno now,
> >>>> which is extremely useful for documenting significant changes in the
> >>>> code base that need to be reflected up. We've dropped UpgradeImpact
> for
> >>>> an upgrade comment in reno, which is *so* much better.
> >>>>
> >>>> It seems like using reno instead of commit message tags would be much
> >>>> better for everyone here.
> >>>
> >>> The goal of DocImpact is to notify the Documentation team about changes
> >>> - currently done via bugs in launchpad so that manuals can be easily
> >>> updated. How would this tracking work with docimpact?
> >>
> >> Because the current concern seems to be that naked DocImpact tag leaves
> >> people guessing what is important. And I understand that. There is a
> >> whole job now to just check that DocImpact containts a reason after it.
> >>
> >> We now have a very detailed system in reno to describe changes that will
> >> impact people using the code. It lets you do that with the commit and
> >> provide an arbitrarily large amount of content in it describing what and
> >> why you think that's important to reflect up.
> >>
> >> I think it effectively deprecates all *Impact flags. Now we have a place
> >> for that payload.
> >
> >
> > We - Sean, Anne Gentle, and Jeremy Stanley - just discussed this on
> > #openstack-infra, let me summarize my understanding:
> >
> > Some flags are used for checking before a merge the changes, especially
> > SecurityImpact and APIImpact. These are used for reviewing the changes.
> > This would be nice for DocImpact as well. SecurityImpact creates emails
> > for merged changes, DocImpact creates bugs for merged changes.
> >
> > When the docimpact spec was written, reno was not in use - and later
> > nobody brought it up as alternative idea.
> >
> > The idea going forward is instead of checking the commit message, is to
> > add a special section using reno that explains the changes that are
> > needed. A post-job would run and create bugs or sends out emails like
> > today whenever a new entry gets added. But this would be triggered by
> > special sections in the release-notes and not in the commit message. We
> > also expect/hope that release notes get a good review and thus the
> > quality of these notifications would be improved.
> >
> > Let's look on how exactly we can do this next year,
>
> Definitely.
>
> One other thing. Not running tests on commit messages has been the norm
> for a while. We used to have commit message checks in hacking, but they
> are things that you can't run locally (easily). So people push a
> critical fix, and run local, everything passes. They push to go to
> dinner and things fail. This has gotten in the way of releasing sec
> fixes in the past.
>
> We have also hoped that with gerrit 2.11 the event stream is rich enough
> that we can actually get to the point where by default we don't
> invalidate test results on a commit message change. There are often
> times when people are asked to add bug references, and the development
> team needs to decide if it's worth an extra couple hours (or more) of CI
> delay to do that. That should not have to be a trade off we need to make.
>
> Commit messages are mostly for humans (bug references being an
> exception). We should stick with that if we can. Especially with the
> potential win of keeping Jenkins results on spelling fixes in commit
> messages.
>
>         -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151221/2fbbf6f5/attachment.html>


More information about the OpenStack-dev mailing list