Open Stack

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

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.

I don't really have a better suggestion though, so I guess we could do
some git-review magic to simplify that (fix the filename at ChangeID
generation time and/or have a --releasenote option that autocreates a file).

> - we also create files that roll up all the notes within history
> versions - named by the version. e.g. release-notes/1.2.3.yaml.
> 
> Yaml schema:
> prelude: prelude prose
> notes:
>  - note1
>  - note2
>  - note3

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.

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

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

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

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

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

Thanks,

-- 
Thierry Carrez (ttx)