Should the release manager also add some additional prose at the top of the document before the release is tagged? It could be content similar to other projects NEWS files or content similar we put into a blog post but more terse.
I envision the RM branches off master, adds the extra prose at the top and then tags the commit that adds the additional prose as the rc. On Mon, May 11, 2015 at 3:07 PM, Bill Farner <[email protected]> wrote: > Now that we have started doing more regular releases, one area in need of > improvement is communicating in plain language what is in a release. Our > current change log [1] leaves much to be desired, as it makes it difficult > for even project developers to know what happened in a release. > > Below i have outlined a straw man for how to put together release notes > going forward, please attack it! > > During the development of a release, we record notes about major line items > for features, backwards incompatibilities, deprecations, etc. We commit > these to the CHANGELOG as part of the relevant commits, so that they revert > cleanly. > > An example of a worthy line item would be "Added the 'aurora update wait' > subcommand to block while an update is in progress". As a counter-example, > we should not include line items like "Upgrade to gradle 2.4" and "Fix link > to contributing page". > > When *preparing* for a release, the release manager is responsible for > editing/organizing these line items. The release manager should enlist the > help of other contributors in this process. > > When *creating* a release candidate, the release tool will do as it does > today - collect all tickets with the fixVersion field matching the release > number. The release tool will add these to the CHANGELOG in a section > below the prose. > > > [1] https://github.com/apache/aurora/blob/master/CHANGELOG > > > -=Bill > > -- > Zameer Manji > >
