On 2/19/14, 10:10 PM, Sean Busbey wrote:
On Wed, Feb 19, 2014 at 10:33 PM, Christopher <[email protected]> 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?"
I would think that something like an UPGRADE or any sort of document
would be better served for this. Any other time, there shouldn't be
anything required.
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].
While I agree that would be nice, I don't know of a quantitative way to
determine that. Is "critical" categorized by some Jira priority? Do we
end up omitting something that someone wanted? I feel like we should
just bundle all changes for that release or none at that point.
-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
