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

2016-01-11 Thread Lana Brindley 
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

On 11/01/16 23:42, Sean Dague wrote:



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

Thank you :)

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

I'm happy to try this, as long as the PTL's of the defcore projects agree.

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

- From docs perspective, it removes the triaging burden off us. If teams are 
happy to take that on, I certainly won't stand in their way.

Lana

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-BEGIN PGP SIGNATURE-
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJWlDWBAAoJELppzVb4+KUyhg4H/j2KKMKQDht9qjbIi80L9CgH
dzC59in/iUqRSjkAt44YG9ikwTQ5zPjIerR7Gj6Lmvm4cijWMoU+rhgO+7A07Nb4
sSADhjcshT8KPhJM/c9jf7BbZld7mGRZ7FrwH+FaxL8ESlcCbaEU9qVSxuwVciJy
ZALGroVDnILQmT5jzOLhOTNzuSW2FZlwamDhuV5TUp3LI8sLlnR0+W5K/6gC4Lmr
LEtIlvsEUk/7bNC3915jMiIrQuGwUBdxL0Z6xcPHRhkXHeiJUHvB31+4kxK8FqVc
GTQWJKNi9yAJ/GQ360vbXhY6HNnVTz0Fs22jlneAu48tlJqqtO6g0KHN8NZVHBc=
=T8bN
-END PGP SIGNATURE-

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-11 Thread Tom Fifield 

On 11/01/16 20:08, Sean Dague wrote:

On 01/10/2016 11:31 PM, Lana Brindley wrote:


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/





-Sean




__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-11 Thread Sean Dague 
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:
>> 
>>> 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

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-11 Thread Sean Dague 
On 01/10/2016 11:31 PM, Lana Brindley wrote:

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

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

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-11 Thread Markus Zoeller 
Tom Fifield <t...@openstack.org> wrote on 01/11/2016 01:55:21 PM:

> From: Tom Fifield <t...@openstack.org>
> To: "OpenStack Development Mailing List (not for usage questions)" 
> <openstack-dev@lists.openstack.org>
> Date: 01/11/2016 01:55 PM
> Subject: Re: [openstack-dev] [doc] DocImpact vs. reno
> 
> On 11/01/16 20:08, Sean Dague wrote:
> > On 01/10/2016 11:31 PM, Lana Brindley wrote:
> > 
> >> 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/

At a short glance I would say:

https://review.openstack.org/#/c/165750/ 
config option needs to be set for backwards compatible change
=> should have reno file

https://review.openstack.org/#/c/184153/ 
enables snapshot for parallels. HypervisorSupportMatrix.ini is already
altered within the change => no further action necessary

https://review.openstack.org/#/c/237643/ 
Removes a deprecated config option => should have reno file

https://review.openstack.org/#/c/180202/ 
Enhances flavor extra specs => to this day I don't know how they get 
documented and I'm clueless about a further action

https://review.openstack.org/#/c/242213/ 
changes default values of the policy.json => should have reno file

https://review.openstack.org/#/c/224500/ 
Does the doc change already in the change (config option help)
=> no further action necessary

https://review.openstack.org/#/c/147516/
introduces new config options => should have reno file

Regards, Markus Zoeller (markus_z)


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-11 Thread Doug Hellmann 
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  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
> 
> 

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-10 Thread Lana Brindley 
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

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

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

My experience would indicate that many, many DocImpact bugs are really not 
worthy of relnotes.

> 
>>>
>>> Bugs and relnotes are two very different things.


L

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-BEGIN PGP SIGNATURE-
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJWkzAVAAoJELppzVb4+KUy6wEH/RFw0czHS2JBXgYTEzuk6fg1
IfLCMcCUXoIastmN+6WDaOG2OKps52p89UhJBw9eEyrRgJM6dqMGhyBCAha/7JcE
/tjW5EDnZw97oaPSHhHW6TvUWOtwvt9jzx7x9escXjuDNDR1ARYdFAuuIHoS9468
6XDR+yt7AWPnQ+W4YJTf1/Kw0+V7Jiy8dGXLkxmV0K+2oFlGfSG1yGclQ+yhYOj+
E7+TXEOqHVTyzcD03XyVB8AH4vzpego7pSP+tx9KcpVjCxF5OvvqEmI4aCq+jza4
PvG3nAWIqKKbtMU1K5hdxfnwQSeqVZp/QkLhhj5EMrvJBiy/50gObeALfhc1cIE=
=+E/P
-END PGP SIGNATURE-

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-08 Thread Tom Fifield 

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




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.


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.





Bugs and relnotes are two very different things.

L

Lana Brindley
writer:speaker:blogger
http://lanabrindley.com





__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev







__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-08 Thread Sean Dague 
On 01/07/2016 06:21 PM, Lana Brindley wrote:
> 
>> On 7 Jan 2016, at 2:09 AM, Sean Dague  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.
> 
>>
>> 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.

> 
> Bugs and relnotes are two very different things.
> 
> L
> 
> Lana Brindley
> writer:speaker:blogger
> http://lanabrindley.com
> 
> 
> 
> 
> 
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> 


-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-07 Thread Lana Brindley 

> On 7 Jan 2016, at 2:09 AM, Sean Dague  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?


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

Bugs and relnotes are two very different things.

L

Lana Brindley
writer:speaker:blogger
http://lanabrindley.com





signature.asc
Description: Message signed with OpenPGP using GPGMail
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-06 Thread Jeremy Stanley 
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.
-- 
Jeremy Stanley

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-06 Thread Sean Dague 
On 01/05/2016 11:07 PM, Lana Brindley wrote:
> 
>> On 6 Jan 2016, at 1:19 PM, Jeremy Stanley  wrote:
>>
>> On 2016-01-06 11:43:34 +1100 (+1100), Lana Brindley wrote:
>> [...]
>>> I’m starting to think that DocImpact needs to simply be retired then
>>
>> Alternatively, let the remaining projects which currently auto-open
>> bugs for openstack-manuals switch to opening bugs against themselves
>> and allow their bug triagers to redirect them to the docs team once
>> the requisite details are determined. And then if those projects
>> don't want to do the work of enforcing or researching the reasons
>> for docimpact headers in individual changes, they can decide to stop
>> supporting them on a project-by-project basis.
> 
> Well, we’ve already done that for big tent projects. The new job was the 
> solution for the ‘defcore’ projects, which we were guinea-pigging in Nova 
> before rolling it out to the others. But if Nova rejects it, I think that 
> maybe we’re dead in the water.

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.

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-06 Thread Sean Dague 
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.

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.

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-05 Thread Sean Dague 
On 01/04/2016 08:01 PM, Lana Brindley wrote:
> I’m late to this party because holidays (Thanks Anne for bringing it to
> my attention).
> 
> First of all, sorry this came as a surprise. I tried hard to make sure
> everyone who needed to know knew, but that’s naturally a difficult thing
> to do.
> 
> To the implementation details: I really am struggling to see how Reno
> could be used as a DocImpact replacement, unless you’re going to use it
> to somehow enforce that packages with DocImpact include some kind of
> text file in the commit. That would be complete overkill, and has the
> potential to really mess up the development repos (who needs random text
> files littered around?). Maybe I’m missing something here, though.
> 
> Really, the intent of the job is merely to check for a description after
> the DocImpact tag that gives the docs people a hint as to what you were
> thinking when you added the tag. It’s simply a time saving measure on
> our part, and sometimes a thing that saves a large amount of human time
> needs to take a small amount of compute time. I don’t think that’s a big
> ask, but again, please correct me if I’m wrong.
> 
> In short, I would rather remove the DocImpact facility entirely than try
> and turn a tool designed for a completely different task to this
> problem. However, as this is the first complaint I’ve seen about this
> solution since starting working on this thorny problem nearly a year
> ago, I can’t help but wonder if we’re overreacting? Do people genuinely
> hate this solution enough that we need to go back to the drawing board?

Yes. Because as I described it scuttles a whole other long term goal
(which is being able to update commit messages and keep Jenkins votes).
Voting based on commit messages is a thing we need to not be doing.

You can score based on content in tree, just not commit messages.

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-05 Thread Lana Brindley 

> On 6 Jan 2016, at 1:19 PM, Jeremy Stanley  wrote:
> 
> On 2016-01-06 11:43:34 +1100 (+1100), Lana Brindley wrote:
> [...]
>> I’m starting to think that DocImpact needs to simply be retired then
> 
> Alternatively, let the remaining projects which currently auto-open
> bugs for openstack-manuals switch to opening bugs against themselves
> and allow their bug triagers to redirect them to the docs team once
> the requisite details are determined. And then if those projects
> don't want to do the work of enforcing or researching the reasons
> for docimpact headers in individual changes, they can decide to stop
> supporting them on a project-by-project basis.

Well, we’ve already done that for big tent projects. The new job was the 
solution for the ‘defcore’ projects, which we were guinea-pigging in Nova 
before rolling it out to the others. But if Nova rejects it, I think that maybe 
we’re dead in the water.

L

Lana Brindley
writer:speaker:blogger
http://lanabrindley.com





signature.asc
Description: Message signed with OpenPGP using GPGMail
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-05 Thread Lana Brindley 

> On 6 Jan 2016, at 12:35 AM, Sean Dague  wrote:
> 
> On 01/04/2016 08:01 PM, Lana Brindley wrote:
>> I’m late to this party because holidays (Thanks Anne for bringing it to
>> my attention).
>> 
>> First of all, sorry this came as a surprise. I tried hard to make sure
>> everyone who needed to know knew, but that’s naturally a difficult thing
>> to do.
>> 
>> To the implementation details: I really am struggling to see how Reno
>> could be used as a DocImpact replacement, unless you’re going to use it
>> to somehow enforce that packages with DocImpact include some kind of
>> text file in the commit. That would be complete overkill, and has the
>> potential to really mess up the development repos (who needs random text
>> files littered around?). Maybe I’m missing something here, though.
>> 
>> Really, the intent of the job is merely to check for a description after
>> the DocImpact tag that gives the docs people a hint as to what you were
>> thinking when you added the tag. It’s simply a time saving measure on
>> our part, and sometimes a thing that saves a large amount of human time
>> needs to take a small amount of compute time. I don’t think that’s a big
>> ask, but again, please correct me if I’m wrong.
>> 
>> In short, I would rather remove the DocImpact facility entirely than try
>> and turn a tool designed for a completely different task to this
>> problem. However, as this is the first complaint I’ve seen about this
>> solution since starting working on this thorny problem nearly a year
>> ago, I can’t help but wonder if we’re overreacting? Do people genuinely
>> hate this solution enough that we need to go back to the drawing board?
> 
> Yes. Because as I described it scuttles a whole other long term goal
> (which is being able to update commit messages and keep Jenkins votes).
> Voting based on commit messages is a thing we need to not be doing.
> 
> You can score based on content in tree, just not commit messages.

OK, I wasn’t aware of that requirement.

In that case, I’m starting to think that DocImpact needs to simply be retired 
then …

L

Lana Brindley
writer:speaker:blogger
http://lanabrindley.com





signature.asc
Description: Message signed with OpenPGP using GPGMail
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-05 Thread Jeremy Stanley 
On 2016-01-06 11:43:34 +1100 (+1100), Lana Brindley wrote:
[...]
> I’m starting to think that DocImpact needs to simply be retired then

Alternatively, let the remaining projects which currently auto-open
bugs for openstack-manuals switch to opening bugs against themselves
and allow their bug triagers to redirect them to the docs team once
the requisite details are determined. And then if those projects
don't want to do the work of enforcing or researching the reasons
for docimpact headers in individual changes, they can decide to stop
supporting them on a project-by-project basis.
-- 
Jeremy Stanley

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2016-01-04 Thread Lana Brindley 
I’m late to this party because holidays (Thanks Anne for bringing it to my 
attention).

First of all, sorry this came as a surprise. I tried hard to make sure everyone 
who needed to know knew, but that’s naturally a difficult thing to do.

To the implementation details: I really am struggling to see how Reno could be 
used as a DocImpact replacement, unless you’re going to use it to somehow 
enforce that packages with DocImpact include some kind of text file in the 
commit. That would be complete overkill, and has the potential to really mess 
up the development repos (who needs random text files littered around?). Maybe 
I’m missing something here, though.

Really, the intent of the job is merely to check for a description after the 
DocImpact tag that gives the docs people a hint as to what you were thinking 
when you added the tag. It’s simply a time saving measure on our part, and 
sometimes a thing that saves a large amount of human time needs to take a small 
amount of compute time. I don’t think that’s a big ask, but again, please 
correct me if I’m wrong.

In short, I would rather remove the DocImpact facility entirely than try and 
turn a tool designed for a completely different task to this problem. However, 
as this is the first complaint I’ve seen about this solution since starting 
working on this thorny problem nearly a year ago, I can’t help but wonder if 
we’re overreacting? Do people genuinely hate this solution enough that we need 
to go back to the drawing board?

Lana

> On 22 Dec 2015, at 10:33 AM, Doug Hellmann  wrote:
> 
> 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

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

2015-12-21 Thread Doug Hellmann 
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?

Doug

> 
> Let's look on how exactly we can do this next year,
> 
> Andreas

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2015-12-20 Thread Joshua Hesketh 
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  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

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

2015-12-18 Thread Sean Dague 
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

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.

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.

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2015-12-18 Thread Sean Dague 
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.

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2015-12-18 Thread Anne Gentle 
On Fri, Dec 18, 2015 at 12: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
>
> 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.
>
>
Lana talked to infra first, specifically Josh Hesketh if my memory serves,
and I hadn't heard there would be any CI impact -- what's the root cause?
Not sure I get why this spec is part of a technical node requirement
change, so please explain more, or Josh please explain more. Then we can
dig in further. Lana's out til the new year and this is my last day for the
year too so let's see what we need to do short term and long term.

Seems especially odd when this should be a low patch volume time so help me
understand the tie-in.


> 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.
>
>
To me, reno is for release notes only, not for doc impact further than
release notes. DocImpact is for any document and for a while the number of
bugs generated in openstack-manuals were too numerous to be meaningfully
triaged.


> It seems like using reno instead of commit message tags would be much
> better for everyone here.
>
>
It's more complex, let's dig in another layer.

Anne


> -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2015-12-18 Thread Andreas Jaeger 

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?


Andreas
--
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2015-12-18 Thread Andreas Jaeger 

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,

Andreas
--
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2015-12-18 Thread Sylvain Bauza 



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



__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2015-12-18 Thread Sean Dague 
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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev