accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher <ctubb...@apache.org>
Subject Re: [DISCUSS] CHANGES Documents
Date Thu, 20 Feb 2014 04:33:23 GMT
I agree with that a short list would be more valuable to readers.
Further, I do not think a comprehensive history of changes would be in
any way beneficial, nor do I think sub-tickets, tests, or tasks, are
beneficial to report. By including this comprehensive list, we're also
making a lot of assumptions about the value of the issue summary to
users, and I'm not so certain that's enough information, in the
general case, to be meaningful to users without requiring them to
cross-reference JIRA anyway.

For example, consider these two examples of things labeled "New Feature":
1. [ACCUMULO-1488] - support BigDecimal encoding for basic built-in combiners
2. [ACCUMULO-1960] - agitator should support sudo as well

Aside from the fact that these are probably improvements, not actual
new features, can anybody honestly say that an average user will know
what these are referring to without actually looking them up in JIRA?
I suspect not... and these are listed prominently in the "New Feature"
section... something a user would care about.

However, that said, I think Keith's idea of prepending to the CHANGES
list generated by the tool (perhaps without tasks/tests/sub-tickets),
for each released version, is the simplest way to generate and include
them. (That's what I used for 1.5.0).

It's true that 1.5.0 replaced this file, rather than prepended to
it... I'm not sure if that's something we should follow as a precedent
always, or for significant (non-bugfix) version jumps, or not at all.
I would be concerned about carrying on this practice of always
prepending, especially as we approach 1MB in size or larger. Our
tickets are now in the thousands, and the file size could easily grow
out of control. This file certainly won't be of much value if it's too
large to open in a minimal text editor like Notepad.exe (which, in
some versions has a limit of 54KB file size).

However, every 1.5.0 release candidate replaced this file instead of
preserving the history of prior release changes, and nobody noticed
until within this last week, so that might say something about the
value people are actually getting from this file. I strongly suspect
that, if anything, people just want to know the simple answers "What's
New?" and "Does this fix my bug yet?" questions, and I don't think
this file answers either of those questions well in any of the
previous releases. Nor do I think this format lends itself easily to
answering those questions. A per-release "Release Notes" section on
the website would probably be more useful for that purpose, with a
footnote reference to SCM/JIRA for the full list of changes. But, is
there another role the CHANGES file is expected to play which I'm
overlooking?

--
Christopher L Tubbs II
http://gravatar.com/ctubbsii


On Wed, Feb 19, 2014 at 4:53 PM, Eric Newton <eric.newton@gmail.com> 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.
>
> 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.
>
> 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 <josh.elser@gmail.com> 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
>>

Mime
View raw message