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 <alex...@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) __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
