aurora-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bill Farner <wfar...@apache.org>
Subject Re: Human-readable release notes
Date Tue, 12 May 2015 00:10:34 GMT
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 <zmanji@apache.org> 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 <wfarner@apache.org> 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
> >
> >
>

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