Open Stack

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.

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

-- 
Thierry Carrez (ttx)