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

Sylvain Bauza sbauza at redhat.com
Fri Dec 18 21:16:05 UTC 2015



Le 18/12/2015 20:31, Andreas Jaeger a écrit :
> 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,
>

FWIW, below are the Nova code-review instructions for when a reno change 
is needed, including doc related changes. Comments welcome if we need to 
be clearer.

http://docs.openstack.org/developer/nova/code-review.html#when-a-release-note-is-needed

> Andreas




More information about the OpenStack-dev mailing list