Open Stack

Excerpts from Thierry Carrez's message of 2015-08-27 11:20:05 +0200:
> Doug Hellmann wrote:
> > Excerpts from Robert Collins's message of 2015-08-19 11:04:37 +1200:
> >> 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 changed this to using a "long enough" random number as a prefix, with
> > a "slug" value provided by the release note author to help identify what
> > is in the file.
> > 
> > I think maybe 8 hex digits for the prefix. Or should we go full UUID?
> > 
> > The slug might be something like "bug xxxx" or "removing option foo"
> > which would be converted to a canonical form, removing whitespace in the
> > filename. The slug can be changed, to allow for fixing typos, but the
> > prefix needs to remain the same in order for the note to be recognized
> > as the same item.
> 
> Random hex digit prefix feels overkill and not really more user-friendly
> than ChangeIDs. Robert's initial proposal used ChangeIDs as a way to map
> snippets to commits, and then to a given release. How would that work
> with UUID+slugs ? Wondering if a one-directory-per-release structure
> couldn't work instead.

reno [1] creates the prefix for you automatically, and uses the git logs
to figure out which files belong in which release. So the notes author does
not need to organize the files at all.

> 
> >> 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)
> > 
> > Rather than sorting, which would change the order of notes as new items
> > are added, what about listing them in an order based on when they were
> > added in the history? We can track the first time a note file appears,
> > so we can maintain the order even if a note is modified.
> 
> +1 That would match the way release notes are produced now (snippets
> sorted in order of addition).
> 

Very good, that's what it does now. I still need to work on the
sphinx integration, and python 3 support, but I think version 0.1.1
is starting to be usable for this release.

Doug

[1] https://github.com/dhellmann/reno (I'll be moving this into gerrit
next week)