Open Stack

Doug Hellmann wrote:
> Excerpts from Robert Collins's message of 2015-08-04 06:43:48 +1200:
>> On 4 August 2015 at 02:46, Alexis Lee <alexisl at hp.com> wrote:
>>> Whichever solution we pick - should we also adopt it on master? Naively
>>> it sounds useful to be able to generate release notes for master too.
>>> And this avoids inconsistency between master and stable beyond that
>>> required to rebase.
>>>
>>> Explanations of the many ways I'm wrong are always appreciated.
>>
>> I think you're right on.
>>
>> Something with the same process as ChangeLog generation today - read
>> from git, process, output document - will be much less fragile for
>> merges.
> 
> We could use the same convention for highlighting changes in libraries,
> and pull the messages out for the release announcements.

Right, the key difference between release notes and changelogs is that
release notes are a curated set of significant highlights.

> How detailed do we want release notes to be? For example, do we need to
> worry about supporting multiple paragraphs or ASCII art or anything like
> that?

Looking at our current release notes, they are a set of bullet points of
a pre-determined type. Types vary slightly between master and stable:

Master release notes (https://wiki.openstack.org/wiki/ReleaseNotes/Kilo)
currently contain three/four sections:

* Key new features
* Known issues
* Upgrade notes
* (Other notes)

[ "Known issues" are generally used to list known bugs that we didn't
have time to fix (or couldn't find a good fix for) at release time. So
there is no related commit. How would we push those ? ]

Stable release notes
(https://wiki.openstack.org/wiki/ReleaseNotes/2015.1.1) currently list:

* (Upgrade notes) -- hopefully never needed
* Security fixes
* Bugs fixed (just links to Launchpad lists)

To answer your question, I don't think we need to support complex
entries with multiple paragraphs or ascii art: single bullet points are
probably enough. A simple grammar of predetermined headers should do the
trick.

We also might need a mechanism to add to release notes when we realize
after the fact that a specific commit in past history warrants a
highlight. Would some kind of no-change commit do the trick ?

-- 
Thierry Carrez (ttx)