On Apr 16, 2008, at 4:23 PM, Doug Cutting wrote:
Nigel Daley wrote:
We've discussed all this before when the new fields were proposed.
I know. And I never really got it then. I'm not trying to be
difficult. Honest!
2. CHANGES.txt. We include one message per JIRA issue here,
organized into sections. These are meant to be user-readable.
When combined with updates to documentation (javadoc & forrest),
they should be sufficient for end users to understand how a
change will affect them.
These are almost always written by the committer (who may not have
been the submitter or reviewer on the issue). They are written
for *every* issue (ie all 207+ in Hadoop 0.17) and rarely (ever?)
explain the user impact
That's a bug that we should fix. I don't yet see how adding a new
mechanism fixes that. Shouldn't we just raise the standards for
these messages? There's no reason they can't be edited again after
the initial commit if they're found lacking.
But how do you get around the noise? User's don't want to be
presented with every little doc/test/bug/improvement. But there are
some significant improvements and bug fixes they need to know about.
The CHANGES.txt can't address that IMO.
The advantages of the new release note field in Jira that folks
are being asked to fill in are:
- written by the patch submitter (issue assignee) and not the
committer
- written only for certain issues that are release noteworthy
- should describe the change and what the user needs to do about
it (see release note on http://issues.apache.org/jira/browse/
HADOOP-1986 for an great example)
But they're not included in the release, so that folks who download
the release don't have the list of changes handy. Stuff in Jira is
edittable by anyone. Documentation for a release is part of what
we sign off on when we vote for a release. Typically this means
that all critical documentation is in subversion so that it can be
reviewed as it is committed and again when we vote on a release.
Umm, I was planning to build the release note doc and check it into
the release.
