[openstack-dev] [doc] DocImpact vs. reno
doug at doughellmann.com
Mon Dec 21 23:33:44 UTC 2015
Excerpts from Andreas Jaeger's message of 2015-12-18 20:31:04 +0100:
> 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.
So you want to add a special section to the reno note file, similar to
"upgrade" and "fixes" but to replace documentation impact notes? What
would use the contents?
> Let's look on how exactly we can do this next year,
More information about the OpenStack-dev