On Wed, Feb 19, 2014 at 4:53 PM, Eric Newton <[email protected]> wrote:
> I think generated CHANGES files are a disservice to the reader. > > A short list of the major differences from the last release should be > given. > It would be nice to create a better release notes. I was poking around on the web reading about release notes. These android release notes[1] are an example of summarizing whats in the release in a nice way. Seems very user friendly. For example the decision to not support RFC2549 is communicated very clearly to the user. [1] http://developer.android.com/sdk/RELEASENOTES.html > > For a bug release, a short list of the critical bugs should be given after > the .0 release. > > So, 1.4.1 would list the 1.4.0 features, and the critical bugs that caused > the 1.4.1 release to be made. > 1.4.2 would list 1.4.0 features, 1.4.1 and 1.4.2 critical bug fixes. > > Basically, I want to quickly understand if I should upgrade (or not). > > If people want the full list, they can get it from JIRA. > > I would also be fine with a CHANGES file with a URL reference to JIRA. > One problem w/ this is that over time the link may stop working. Software can be used for many years after release. I do not think that we need stop including whats generated from jira if we also produce nice user friendly release notes. I think both are appropriate for different audiences. > > I personally would not down-vote a release because it has an accurate > CHANGES file, but not the content I think it should have. > > -Eric > > > > On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <[email protected]> wrote: > > > The CHANGES document that is included in an Accumulo release contains > some > > set of changes from a previous release which presently contain the > > following information: > > > > 1) Issue Type (Task, Bug, Feature, etc) > > 2) Issue Number (ACCUMULO-1234) > > 3) Issue Subject > > > > There have been various preferences expressed, primarily over IRC, on > > which changes should be contained and how they should be formatted. The > > largest consensus, and what I believe we should do, is as follows: > > > > Entries in a CHANGES file should contain issues, delimited by minor > > version within the major version[1], grouped by issue type. The minor > > version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1, > then > > 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not* > be > > included in this CHANGES file. > > > > Opinions? The results of this discussion will be documented on the > > release-making page[2] of the website for future reference. > > > > - Josh > > > > [1] Major and minor version here is referred to as Y and Z of version > > strings of the form: X.Y.Z (not as prescribed by semver, proper) > > [2] http://accumulo.apache.org/releasing.html > > >
