[openstack-dev] [stable] [infra] How to auto-generate stable release notes

Kuvaja, Erno kuvaja at hp.com
Wed Aug 19 11:19:00 UTC 2015


> -----Original Message-----
> From: Robert Collins [mailto:robertc at robertcollins.net]
> Sent: Wednesday, August 19, 2015 11:38 AM
> To: OpenStack Development Mailing List (not for usage questions)
> Subject: Re: [openstack-dev] [stable] [infra] How to auto-generate stable
> release notes
> 
> On 19 August 2015 at 21:19, Thierry Carrez <thierry at openstack.org> wrote:
> > Robert Collins wrote:
> >> [...]
> >> Proposed data structure:
> >> - create a top level directory in each repo called release-notes
> >> - within that create a subdirectory called changes.
> >> - within the release-notes dir we place yaml files containing the
> >> release note inputs.
> >> - within the 'changes' subdirectory, the name of the yaml file will
> >> be the gerrit change id in a canonical form.
> >>    E.g. I1234abcd.yaml
> >>    This serves two purposes: it guarantees file name uniqueness (no
> >> merge conflicts) and lets us
> >>    determine which release to group it in (the most recent one, in
> >> case of merge+revert+merge patterns).

We try to have python-glanceclient and glance_store including release notes upon the release time. We use in tree doc/source/index.rst for ease of access. This provides our release notes through: docs.openstack.org/developer/python-glanceclient/ and you can easily follow up stable branches via git: https://github.com/openstack/python-glanceclient/blob/stable/kilo/doc/source/index.rst

I've been trying to push mentality in to our community that last thing before release, we merge release notes update and tag that. What comes to stable, I think it's worth of adding release notes in the backport workflow.
> >
> > One small issue I see with using changeid in the filename is that it
> > prevents people from easily proposing a backport with a release note
> > snippet in them (since they can't predict the changeID). They will
> > have to get it generated and then amend their commit.
> 
> Backports typically use the original changeID - they will if they use git cherry-
> pick.
> 
> > I think we need to enforce some more structure. Release notes are
> > easier to read if you group them by category. For stable branches you
> > should put "critical upgrade notes" first, then "security updates",
> > then random release notes. For master branch notes we usually have
> > "critical upgrade notes", then "major features", then "known issues",
> > then random release notes. So I would encourage a slightly more
> > detailed schema with categories to keep consistency and readability.

Strong maybe, pointless in stable if our aim is to have each commit being release or if we anyways have one or two changes per topic.

This would make sense on initial release from master excluding libs and clients which tends to have less changes per release anyways.
> 
> Sure - please fill it in :). I was winging it, since I don't do release notes, I had
> no idea of your needs.
> 
> >> Processing:
> >> 1) determine the revisions we need to generate release notes for. By
> >> default generate notes for the current minor release. (E.g. if the
> >> tree version is 1.2.3.dev4 we would generate release notes for 1.2.0,
> >> 1.2.1, 1.2.2, 1.2.3[which dev4 is leading up to]).
> >
> > How would that work in a post-versioned world ? What would you
> > generate if the tree version is 1.2.3.post12 ?
> 
> 1.2.3 is still the version, not that we can use post versions at all with pbr.
> (Short story - we can't because we used them wrongly and we haven't had
> nearly enough time to flush out remaining instances in the wild).
> 
> >> 2) For each version: scan all the commits to determine gerrit change-id's.
> >>  i) read in all those change ids .yaml files and pull out any notes within
> them.
> >>  ii) read in any full version yaml file (and merge in its contained
> >> notes)
> >>  iii) Construct a markdown document as follows:
> >>   a) Sort any preludes (there should be only one at most, but lets
> >> not error if there are multiple)
> >>   b) sort any notes
> >
> > We would sort them by category.
> 
> The requirement for deterministic results means we'd just sort them.
> If they are divided into categories, we'd sort the list of categories (perhaps
> according to some schema) and then within each category sort the notes.
> 
> >>   c) for each note transform it into a bullet point by prepending its
> >> first line with '- ' and every subsequent line with '  ' (two spaces
> >> to form a hanging indent).
> >>   d) strip any trailing \n's from everything.
> >>   e) join the result - '\n'.join(chain(preludes, notes))
> >>  iv) we output the resulting file to release-notes/$version.md where
> >> $version is the pbr reported version for the tree (e.g. in the
> >> example above it would be 1.2.3.dev4, *not* 1.2.3).
> >
> > So you would have release-notes/1.2.2.yaml and release-notes/1.2.2.md
> > in the same directory, with one being a subset of the data present in
> > the other ? That feels a bit confusing. I would rather use two
> > separate directories (source and output) for that.
> 
> If you like, sure. Though the thing I was thinking was that for very old things
> we might generate the md file, delete the yaml, and commit to the tree.
> 
> >> 3) possibly symlink the highest output version to ./RELEASENOTES.md
> >> or something, so other tooling can look for a constant value.
> >
> > +1
> >
> >> If we want to put release notes in sdists, we can have pbr do this,
> >> otherwise it could just be built entirely separately.
> >
> > I think we need to put release notes in sdists, so that people
> > consuming stable branches from a random commit can still get
> > work-in-progress releasenotes for the upcoming version.
> 
> Those two things are disconnected. Consuming a random commit doesn't
> imply sdist - nor does it preclude it.
> 
> We don't *currently* generate release notes in sdists. Whats the driver for
> adding it? [perhaps as a use case so we can flush out hidden assumptions we
> have]
> 
> >> I recommend we start with it entirely separate: part of the
> >> release-management tooling.
> >
> > That could work, for example, for the liberty release. I think for
> > stable branches we'll need releasenotes published in the sdists, for
> > the above-mentioned reason.
> 
> I don't understand the reason well enough to follow it.
> 
> -Rob
> 
> 
> --
> Robert Collins <rbtcollins at hp.com>
> Distinguished Technologist
> HP Converged Cloud

It would be extremely great if we did not need to overcomplicate the workflow with the release notes. They are not nuclear science and lets not try to make it complicate enough to need a doctorate to understand how to a) add them b) correct/fix them c) troubleshoot the generation _when_ something breaks in that workflow.

- Erno
> 
> __________________________________________________________
> ________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-
> request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



More information about the OpenStack-dev mailing list