On Apr 16, 2008, at 3:56 PM, Doug Cutting wrote:
Nigel Daley wrote:
As you know, we've added a release note field in Jira from which
we can build a reasonable set of user facing release notes.
I always thought that the message in CHANGES.txt should be written
for end-users. Isn't that the case? If so, shouldn't we strive to
improve & better structure these instead or in addition?
I guess I'm still unclear on the difference between these.
We've discussed all this before when the new fields were proposed.
There are now three places where we include summary descriptions of
changes:
1. The commit message. This should usually be minimal, enough to
jog the memory, and always with a reference to the JIRA issue, but
it does not need to be sufficient for end users.
This is written by the committer.
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
3. Jira release notes. See (2), above.
I assume by Jira release notes you mean the ones generated by Jira
already. These are simply a link to each issue (all 207+) and the
summary line from the issue. The summary line is frequently
unrelated to actual fix and user impact.
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)
Nige
