I would advocate for a second file to CHANGELOG, a NEWS file, which contains details on security issues, upgrade notes and any important tickets to call out in a given release. If a developer is working on a ticket and it meets any of this criteria then that file should be updated as part of the patch
-Jake On Mon, May 11, 2015 at 8:10 PM, Bill Farner <[email protected]> wrote: > Yes, you spelled out something i was thinking but failed to illustrate. I > think a high-level summary is extremely useful. With regard to the commit > semantics, i don't see why it needs to be off master, in fact - it seems > like it *should* be on master. > > -=Bill > > On Mon, May 11, 2015 at 4:23 PM, Zameer Manji <[email protected]> wrote: > > > 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 > > > > > > > > >
