aurora-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bill Farner <wfar...@apache.org>
Subject Human-readable release notes
Date Mon, 11 May 2015 22:07:03 GMT
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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message