Re: [openstack-dev] [doc] DocImpact vs. reno
-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
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
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
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
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
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 Daguewrote: > > 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
-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 Daguewrote: 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
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 Daguewrote: 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
On 01/07/2016 06:21 PM, Lana Brindley wrote: > >> On 7 Jan 2016, at 2:09 AM, Sean Daguewrote: >> >> 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
> On 7 Jan 2016, at 2:09 AM, Sean Daguewrote: > > 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
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
On 01/05/2016 11:07 PM, Lana Brindley wrote: > >> On 6 Jan 2016, at 1:19 PM, Jeremy Stanleywrote: >> >> 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
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
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
> On 6 Jan 2016, at 1:19 PM, Jeremy Stanleywrote: > > 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
> On 6 Jan 2016, at 12:35 AM, Sean Daguewrote: > > 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
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
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 Hellmannwrote: > > 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
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
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 Daguewrote: > 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
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
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
On Fri, Dec 18, 2015 at 12:03 PM, Sean Daguewrote: > 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
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
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
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
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