Mailing-List: contact dev-help@accumulo.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@accumulo.apache.org
Received-SPF: pass (athena.apache.org: domain of busbey@cloudera.com
 designates 209.85.192.41 as permitted sender)
MIME-Version: 1.0
In-Reply-To: 
 <CAL5zq9YQF252KDBU2n==yD9v-OJQyF8dyoyjPhqpwxTRFQor+g@mail.gmail.com>
References: <53052278.8050402@gmail.com>
 <CADxc9B=jnnUyPeUL+APhYh5DQ6tqC=HdjF+quC92M-RfzxfSPg@mail.gmail.com>
 <CAL5zq9YQF252KDBU2n==yD9v-OJQyF8dyoyjPhqpwxTRFQor+g@mail.gmail.com>
From: Sean Busbey <busbey+lists@cloudera.com>
Date: Thu, 20 Feb 2014 00:10:52 -0600
Message-ID: 
 <CAGHyZ6LsSqS8N_ag=cQpqHzVMA6SFZ+a28a=xa8xm1iJQTs=yQ@mail.gmail.com>
Subject: Re: [DISCUSS] CHANGES Documents
To: "dev@accumulo apache. org" <dev@accumulo.apache.org>
Content-Type: multipart/alternative; boundary=047d7beba10c45fe3804f2d05fa5

--047d7beba10c45fe3804f2d05fa5
Content-Type: text/plain; charset=UTF-8

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 agree that a section on the website would be more broadly useful than in
the distribution (esp if we're authoring this rather than generating it via
jira). I think it would be beneficial, however, to use Markdown in the CMS
to author and then include that file directly in the distro as a snapshot
for those offline. Authoring in the CMS would hopefully also encourage us
to update the document incrementally rather than making the release manager
handle it at the end.

The more I reread this thread, the more I like the release notes described
by Eric[2].

-Sean

[1]: To the public API, at a minimum. I think there are a few other things
that practically speaking we should also call out, like changes to implicit
configuration via defaults, the core iterators, or the Constraint interface.

[2]: http://s.apache.org/ih9

--047d7beba10c45fe3804f2d05fa5--