Open Stack

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

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