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

Sean Dague sean at dague.net
Mon Jan 11 13:42:55 UTC 2016

On 01/11/2016 07:55 AM, Tom Fifield wrote:
> On 11/01/16 20:08, Sean Dague wrote:
>> On 01/10/2016 11:31 PM, Lana Brindley wrote:
>> <snip>
>>> Wow. That'll make the release notes process painful this round ... o.O
>> Hmmm. In my mind it will make it a lot easier. In the past we end up
>> getting to the release and sit around and go "hmmm, what did we change
>> in the last 6 months that people care about?" And forget 90% of it. This
>> does the work up front. We can then just provide a final edit and
>> summary of highlights, and we're done.
>> Having spoke with ops over the years, no one is going to be upset if we
>> tell them all the changes that might impact them.
>>>> 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/
>> I can only speak on the Nova change (as that's a team I review for).
>> You'll see this comment in there -
>> https://review.openstack.org/#/c/180202/31//COMMIT_MSG - a relnote was
>> expected for the patch series. Whether or not it managed to slip
>> through, I don't know.
> Confirmed - no relnotes for this.
>>>> 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.
>> Can you provide some references? Again, my imagination doesn't really
>> come up with a lot of Nova changes that would be valid DocImpact but
>> wouldn't need a reno. I can see bugs filed against Docs explicitly
>> because there is a mismatch.
> Since you wanted to focus only on nova, here's some more DocImpact
> reviews that did not have relnotes. Again, I basically haven't read
> these -  if someone wanted to do this properly, much appreciated.
> https://review.openstack.org/#/c/165750/
> https://review.openstack.org/#/c/184153/
> https://review.openstack.org/#/c/237643/
> https://review.openstack.org/#/c/180202/
> https://review.openstack.org/#/c/242213/
> https://review.openstack.org/#/c/224500/
> https://review.openstack.org/#/c/147516/

Looking through the list it looks like there are a few that merged
before reno. A bunch where DocImpact is being used by the Author as "I
changed docs", and a couple that I have no idea why the flag was stuck
in there at all. A number of the DocImpact tags even had the extra
context line, which seemed to be description of what docs the author
changed in the patch.

This conversation has gone on long enough I've completely lost the
problem we're trying to solve and the constraints around it.

I'd like to reset the conversation a little.

Goal: to not flood Docs team with vague bugs that are hard to decypher

Current Approach: machine enforce extra words after DocImpact (not
reviewed by doc team)

Downsides with current approach:
* it's a machine, not people, so clarity isn't guarunteed.
* the reviewers of the commit message aren't the people that will have
to deal with it,   leading to bad quality control on the reviews.
* extra jobs which cause load and inhibit our ability to stop reseting
jenkins votes on commit message changes

My Alternative Approach:

File doc bugs against project team instead of doc team. Make passing bug
to Doc team a project team responsibility to ensure context is provided
when it's needed.

This also means there is a feedback loop between the reviewers and the
folks having to deal with the artifacts (on first pass).


Sean Dague

More information about the OpenStack-dev mailing list