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 22:33:39 GMT
On Thu, Feb 20, 2014 at 1:00 PM, Keith Turner <keith@deenlo.com> wrote:
> On Thu, Feb 20, 2014 at 1:10 AM, Sean Busbey <busbey+lists@cloudera.com>wrote:
>
>> On Wed, Feb 19, 2014 at 10:33 PM, Christopher <ctubbsii@apache.org> wrote:
>>
>> >
>> > 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?
>> >
>>
>>
>> The main one I can think of is "Will this break my already working system
>> in some other way?"
>>
>> So in addition to your two above major areas, I'd say a section on known
>> backwards incompatible changes[1] would cover things.
>>
>
> I would really like to see this type of information called out in release
> notes.
>
> There have been a lot of good ideas mentioned.  What do we want to do for
> 1.5.1?  I would not be opposed to waiting a few days on the 1.5.1 release
> if someone wants to create nice user friendly release notes.  Or for 1.5.1
> we could just continue to do what was done for 1.4.X releases.   For 1.6.0
> I think we should create a user friendly summary of whats important in the
> release.

I think for 1.5.1, it is sufficient to include a section of 1.5.1
changes, followed by 1.5.0 changes. I think tasks, tests, and
sub-tasks should be excluded from this list entirely. In the future,
we can devote more time to ensuring summaries are more useful, but I
wouldn't concern ourselves with that today, for 1.5.1. One thing I do
want to do for 1.5.1 (and will do immediately after composing this),
is update those issues I mentioned which are currently labeled as "New
Feature", which should be labeled "Improvement".

I think we should make it a point to create a release notes html page
for each release, linked on the download page instead of the CHANGES
file, since they seem to serve different purposes. I think the release
notes should contain the things which people have suggested throughout
this thread, such as: prominent features, major bug fixes, and
incompatibility notices, upgrade information, and known bugs that we
may discover shortly after release. This document does not need to be
final, and can be updated at any time (pre-release, after vote, after
we find a major bug 3 months from now, whenever).

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

Mime
View raw message