Re: [openstack-dev] [release] using reno for libraries
On 11/28/2015 02:48 PM, Doug Hellmann wrote: Excerpts from Doug Hellmann's message of 2015-11-27 10:21:36 -0500: Liaisons, We're making good progress on adding reno to service projects as we head to the Mitaka-1 milestone. Thank you! We also need to add reno to all of the other deliverables with changes that might affect deployers. That means clients and other libraries, SDKs, etc. with configuration options or where releases can change deployment behavior in some way. Now that most teams have been through this conversion once, it should be easy to replicate for the other repositories in a similar way. Libraries have 2 audiences for release notes: developers consuming the library and deployers pushing out new versions of the libraries. To separate the notes for the two audiences, and avoid doing manually something that we have been doing automatically, we can use reno just for deployer release notes (changes in support for options, drivers, etc.). That means the library repositories that need reno should have it configured just like for the service projects, with the separate jobs and a publishing location different from their existing developer documentation. The developer docs can continue to include notes for the developer audience. I've had a couple of questions about this split for release notes. The intent is for developer-focused notes to continue to come from commit messages and in-tree documentation, while using reno for new and additional deployer-focused communication. Most commits to libraries won't need reno release notes. This looks like unnecessary overcomplication. Why not use such a convenient tool for both kinds of release notes instead of having us invent and maintain one more place to put release notes, now for developers? It's already not so easy to explain reno to newcomers, this idea makes it even harder... Doug After we start using reno for libraries, the release announcement email tool will be updated to use those same notes to build the message in addition to looking at the git change log. This will be a big step toward unifying the release process for services and libraries, and will allow us to make progress on completing the automation work we have planned for this cycle. It's not necessary to add reno to the liberty branch for library projects, since we tend to backport far fewer changes to libraries. If you maintain a library that does see a lot of backports, by all means go ahead and add reno, but it's not a requirement. If you do set up multiple branches, make sure you have one page that uses the release-notes directive without specifing a branch, as in the oslo.config example, to build notes for the "current" branch to get releases from master and to serve as a test for rendering notes added to stable branches. Thanks, Doug __ 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] [release] using reno for libraries
On 11/30/2015 05:14 PM, Doug Hellmann wrote: Excerpts from Dmitry Tantsur's message of 2015-11-30 10:06:25 +0100: On 11/28/2015 02:48 PM, Doug Hellmann wrote: Excerpts from Doug Hellmann's message of 2015-11-27 10:21:36 -0500: Liaisons, We're making good progress on adding reno to service projects as we head to the Mitaka-1 milestone. Thank you! We also need to add reno to all of the other deliverables with changes that might affect deployers. That means clients and other libraries, SDKs, etc. with configuration options or where releases can change deployment behavior in some way. Now that most teams have been through this conversion once, it should be easy to replicate for the other repositories in a similar way. Libraries have 2 audiences for release notes: developers consuming the library and deployers pushing out new versions of the libraries. To separate the notes for the two audiences, and avoid doing manually something that we have been doing automatically, we can use reno just for deployer release notes (changes in support for options, drivers, etc.). That means the library repositories that need reno should have it configured just like for the service projects, with the separate jobs and a publishing location different from their existing developer documentation. The developer docs can continue to include notes for the developer audience. I've had a couple of questions about this split for release notes. The intent is for developer-focused notes to continue to come from commit messages and in-tree documentation, while using reno for new and additional deployer-focused communication. Most commits to libraries won't need reno release notes. This looks like unnecessary overcomplication. Why not use such a convenient tool for both kinds of release notes instead of having us invent and maintain one more place to put release notes, now for In the past we have had rudimentary release notes and changelogs for developers to read based on the git commit messages. Since deployers and developers care about different things, we don't want to make either group sift through the notes meant for the other. So, we publish notes in different ways. Hmm, so maybe for small libraries with few changes it's still fine to publish them together, what do you think? The thing that is new here is publishing release notes for changes in libraries that deployers need to know about. While the Oslo code was in the incubator, and being copied into applications, it was possible to detect deployer-focused changes like new or deprecated configuration options in the application and put the notes there. Using shared libraries means those changes can happen without application developers being aware of them, so the library maintainers need to be publishing notes. Using reno for those notes is consistent with the way they are handled in the applications, so we're extending one tool to more repositories. developers? It's already not so easy to explain reno to newcomers, this idea makes it even harder... Can you tell me more about the difficulty you've had? I would like to improve the documentation for reno and for how we use it. Usually people are stuck at the "how do I do this at all" stage :) we've even added it to the ironic developer FAQ. As to me, the official reno documentation is nice enough (but see below), maybe people are not aware of it. Another "issue" (at least for our newcomers) with reno docs is that http://docs.openstack.org/developer/reno/usage.html#generating-a-report mentions the "reno report" command which is not something we all actually use, we use these "tox -ereleasenotes" command. What is worse, this command (I guess it's by design) does not catch release note files that are just created locally. It took me time to figure out that I have to commit release notes before "tox -ereleasenotes" would show them in the rendered HTML. Finally, people are confused by how our release note jobs handle branches. E.g. ironic-inspector release notes [1] currently seem to show release notes from stable/liberty (judging by the version), so no current items [2] are shown. [1] http://docs.openstack.org/releasenotes/ironic-inspector/unreleased.html [2] for example http://docs-draft.openstack.org/18/250418/2/gate/gate-ironic-inspector-releasenotes/f0b9363//releasenotes/build/html/unreleased.html Doug Doug After we start using reno for libraries, the release announcement email tool will be updated to use those same notes to build the message in addition to looking at the git change log. This will be a big step toward unifying the release process for services and libraries, and will allow us to make progress on completing the automation work we have planned for this cycle. It's not necessary to add reno to the liberty branch for library projects, since we tend to backport far fewer changes to libraries. If you maintain a library that does see a lot of backports, by all means
Re: [openstack-dev] [release] using reno for libraries
Excerpts from Dmitry Tantsur's message of 2015-11-30 10:06:25 +0100: > On 11/28/2015 02:48 PM, Doug Hellmann wrote: > > Excerpts from Doug Hellmann's message of 2015-11-27 10:21:36 -0500: > >> Liaisons, > >> > >> We're making good progress on adding reno to service projects as > >> we head to the Mitaka-1 milestone. Thank you! > >> > >> We also need to add reno to all of the other deliverables with > >> changes that might affect deployers. That means clients and other > >> libraries, SDKs, etc. with configuration options or where releases > >> can change deployment behavior in some way. Now that most teams > >> have been through this conversion once, it should be easy to replicate > >> for the other repositories in a similar way. > >> > >> Libraries have 2 audiences for release notes: developers consuming > >> the library and deployers pushing out new versions of the libraries. > >> To separate the notes for the two audiences, and avoid doing manually > >> something that we have been doing automatically, we can use reno > >> just for deployer release notes (changes in support for options, > >> drivers, etc.). That means the library repositories that need reno > >> should have it configured just like for the service projects, with > >> the separate jobs and a publishing location different from their > >> existing developer documentation. The developer docs can continue > >> to include notes for the developer audience. > > > > I've had a couple of questions about this split for release notes. The > > intent is for developer-focused notes to continue to come from commit > > messages and in-tree documentation, while using reno for new and > > additional deployer-focused communication. Most commits to libraries > > won't need reno release notes. > > This looks like unnecessary overcomplication. Why not use such a > convenient tool for both kinds of release notes instead of having us > invent and maintain one more place to put release notes, now for In the past we have had rudimentary release notes and changelogs for developers to read based on the git commit messages. Since deployers and developers care about different things, we don't want to make either group sift through the notes meant for the other. So, we publish notes in different ways. The thing that is new here is publishing release notes for changes in libraries that deployers need to know about. While the Oslo code was in the incubator, and being copied into applications, it was possible to detect deployer-focused changes like new or deprecated configuration options in the application and put the notes there. Using shared libraries means those changes can happen without application developers being aware of them, so the library maintainers need to be publishing notes. Using reno for those notes is consistent with the way they are handled in the applications, so we're extending one tool to more repositories. > developers? It's already not so easy to explain reno to newcomers, this > idea makes it even harder... Can you tell me more about the difficulty you've had? I would like to improve the documentation for reno and for how we use it. Doug > > > > > Doug > > > >> > >> After we start using reno for libraries, the release announcement > >> email tool will be updated to use those same notes to build the > >> message in addition to looking at the git change log. This will be > >> a big step toward unifying the release process for services and > >> libraries, and will allow us to make progress on completing the > >> automation work we have planned for this cycle. > >> > >> It's not necessary to add reno to the liberty branch for library > >> projects, since we tend to backport far fewer changes to libraries. > >> If you maintain a library that does see a lot of backports, by all > >> means go ahead and add reno, but it's not a requirement. If you do > >> set up multiple branches, make sure you have one page that uses the > >> release-notes directive without specifing a branch, as in the > >> oslo.config example, to build notes for the "current" branch to get > >> releases from master and to serve as a test for rendering notes > >> added to stable branches. > >> > >> Thanks, > >> Doug > >> > > > > __ > > 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] [release] using reno for libraries
Excerpts from Dmitry Tantsur's message of 2015-11-30 17:58:45 +0100: > On 11/30/2015 05:14 PM, Doug Hellmann wrote: > > Excerpts from Dmitry Tantsur's message of 2015-11-30 10:06:25 +0100: > >> On 11/28/2015 02:48 PM, Doug Hellmann wrote: > >>> Excerpts from Doug Hellmann's message of 2015-11-27 10:21:36 -0500: > Liaisons, > > We're making good progress on adding reno to service projects as > we head to the Mitaka-1 milestone. Thank you! > > We also need to add reno to all of the other deliverables with > changes that might affect deployers. That means clients and other > libraries, SDKs, etc. with configuration options or where releases > can change deployment behavior in some way. Now that most teams > have been through this conversion once, it should be easy to replicate > for the other repositories in a similar way. > > Libraries have 2 audiences for release notes: developers consuming > the library and deployers pushing out new versions of the libraries. > To separate the notes for the two audiences, and avoid doing manually > something that we have been doing automatically, we can use reno > just for deployer release notes (changes in support for options, > drivers, etc.). That means the library repositories that need reno > should have it configured just like for the service projects, with > the separate jobs and a publishing location different from their > existing developer documentation. The developer docs can continue > to include notes for the developer audience. > >>> > >>> I've had a couple of questions about this split for release notes. The > >>> intent is for developer-focused notes to continue to come from commit > >>> messages and in-tree documentation, while using reno for new and > >>> additional deployer-focused communication. Most commits to libraries > >>> won't need reno release notes. > >> > >> This looks like unnecessary overcomplication. Why not use such a > >> convenient tool for both kinds of release notes instead of having us > >> invent and maintain one more place to put release notes, now for > > > > In the past we have had rudimentary release notes and changelogs > > for developers to read based on the git commit messages. Since > > deployers and developers care about different things, we don't want > > to make either group sift through the notes meant for the other. > > So, we publish notes in different ways. > > Hmm, so maybe for small libraries with few changes it's still fine to > publish them together, what do you think? I'm not sure why you would want to do that. Publishing the ChangeLog contents in the developer documentation is (or can be) completely automatic. It should only be possible to add reno notes for deployer-facing changes, and those notes will need to be written in a way the deployer can understand, which is not necessarily a requirement for a commit message. > > The thing that is new here is publishing release notes for changes > > in libraries that deployers need to know about. While the Oslo code > > was in the incubator, and being copied into applications, it was > > possible to detect deployer-focused changes like new or deprecated > > configuration options in the application and put the notes there. > > Using shared libraries means those changes can happen without > > application developers being aware of them, so the library maintainers > > need to be publishing notes. Using reno for those notes is consistent > > with the way they are handled in the applications, so we're extending > > one tool to more repositories. > > > >> developers? It's already not so easy to explain reno to newcomers, this > >> idea makes it even harder... > > > > Can you tell me more about the difficulty you've had? I would like to > > improve the documentation for reno and for how we use it. > > Usually people are stuck at the "how do I do this at all" stage :) we've > even added it to the ironic developer FAQ. As to me, the official reno > documentation is nice enough (but see below), maybe people are not aware > of it. > > Another "issue" (at least for our newcomers) with reno docs is that > http://docs.openstack.org/developer/reno/usage.html#generating-a-report > mentions the "reno report" command which is not something we all > actually use, we use these "tox -ereleasenotes" command. What is worse, > this command (I guess it's by design) does not catch release note files > that are just created locally. It took me time to figure out that I have > to commit release notes before "tox -ereleasenotes" would show them in > the rendered HTML. The reno documentation is written for any user, not just OpenStack developers. Those instructions should work if reno is installed, even though we've wrapped reno in tox to make it simpler to run in the gate. We can add some information about using tox to build locally to the project team guide. I'll look into
Re: [openstack-dev] [release] using reno for libraries
Excerpts from Doug Hellmann's message of 2015-11-27 10:21:36 -0500: > Liaisons, > > We're making good progress on adding reno to service projects as > we head to the Mitaka-1 milestone. Thank you! > > We also need to add reno to all of the other deliverables with > changes that might affect deployers. That means clients and other > libraries, SDKs, etc. with configuration options or where releases > can change deployment behavior in some way. Now that most teams > have been through this conversion once, it should be easy to replicate > for the other repositories in a similar way. > > Libraries have 2 audiences for release notes: developers consuming > the library and deployers pushing out new versions of the libraries. > To separate the notes for the two audiences, and avoid doing manually > something that we have been doing automatically, we can use reno > just for deployer release notes (changes in support for options, > drivers, etc.). That means the library repositories that need reno > should have it configured just like for the service projects, with > the separate jobs and a publishing location different from their > existing developer documentation. The developer docs can continue > to include notes for the developer audience. I've had a couple of questions about this split for release notes. The intent is for developer-focused notes to continue to come from commit messages and in-tree documentation, while using reno for new and additional deployer-focused communication. Most commits to libraries won't need reno release notes. Doug > > After we start using reno for libraries, the release announcement > email tool will be updated to use those same notes to build the > message in addition to looking at the git change log. This will be > a big step toward unifying the release process for services and > libraries, and will allow us to make progress on completing the > automation work we have planned for this cycle. > > It's not necessary to add reno to the liberty branch for library > projects, since we tend to backport far fewer changes to libraries. > If you maintain a library that does see a lot of backports, by all > means go ahead and add reno, but it's not a requirement. If you do > set up multiple branches, make sure you have one page that uses the > release-notes directive without specifing a branch, as in the > oslo.config example, to build notes for the "current" branch to get > releases from master and to serve as a test for rendering notes > added to stable branches. > > Thanks, > Doug > __ 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-dev] [release] using reno for libraries
Liaisons, We're making good progress on adding reno to service projects as we head to the Mitaka-1 milestone. Thank you! We also need to add reno to all of the other deliverables with changes that might affect deployers. That means clients and other libraries, SDKs, etc. with configuration options or where releases can change deployment behavior in some way. Now that most teams have been through this conversion once, it should be easy to replicate for the other repositories in a similar way. Libraries have 2 audiences for release notes: developers consuming the library and deployers pushing out new versions of the libraries. To separate the notes for the two audiences, and avoid doing manually something that we have been doing automatically, we can use reno just for deployer release notes (changes in support for options, drivers, etc.). That means the library repositories that need reno should have it configured just like for the service projects, with the separate jobs and a publishing location different from their existing developer documentation. The developer docs can continue to include notes for the developer audience. After we start using reno for libraries, the release announcement email tool will be updated to use those same notes to build the message in addition to looking at the git change log. This will be a big step toward unifying the release process for services and libraries, and will allow us to make progress on completing the automation work we have planned for this cycle. It's not necessary to add reno to the liberty branch for library projects, since we tend to backport far fewer changes to libraries. If you maintain a library that does see a lot of backports, by all means go ahead and add reno, but it's not a requirement. If you do set up multiple branches, make sure you have one page that uses the release-notes directive without specifing a branch, as in the oslo.config example, to build notes for the "current" branch to get releases from master and to serve as a test for rendering notes added to stable branches. Thanks, Doug __ 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
