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
