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.
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.
Doug
