Open Stack

Thierry Carrez wrote:
> Doug Hellmann wrote:
>> 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.

So I propose we use, starting with stable/liberty backports in two
months, the following commit message headers:

Critical-note: <text>
For a critical release note bullet point, generally if backward
compatibility is broken and/or the upgrade from the original stable
release requires manual intervention. That generally means the stable
branch rules have been pretty broken and this commit got an exception,
so hopefully this is never used.

OSSA: <YYYY-ZZZ>
For commits that correspond to vulnerability fixes.

Release-note: <text>
For general release note bullet point.

pbr could pick up those headers in git commits, build a RELEASENOTES
text file including bullets for the 3 sections (in that order) and
(maybe) add a link to the corresponding Launchpad milestone page for
people interested in seeing bugfix lists. How crazy does that sound ?

We can extend the vocabulary and enable this on master branches as a
second step, but the time-sensitive issue is on stable branches: we want
this ready in 2 months for when we'll start generating stable/liberty
thingies.

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

Any suggestion on how to work around that situation ?

-- 
Thierry Carrez (ttx)