hadoop-common-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nigel Daley <nda...@yahoo-inc.com>
Subject Re: ACTION NEEDED: Hadoop 0.17 Release Notes
Date Wed, 16 Apr 2008 23:06:22 GMT

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  
  - 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)


View raw message