ACTION NEEDED: Hadoop 0.17 Release Notes

[Nigel Daley <nd...@yahoo-inc.com>]

Hadoop Developers,

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.  Candidates  
for release notes are:
  - incompatibilities
  - features
  - major or critical improvements
  - major or critical bug fixes
Of the 207+ issues fixed in Hadoop 0.17, we have 68+ issues that fall  
into the first 3 categories above.  Of those 68, only 12 have release  
notes filled in.  Of those 12, only 2 are written in a user facing  
way (ie. no additional knowledge of the issue needed, described the  
impact, etc.)

IMHO, these 2 issues have exemplary release notes which I suggest you  
read:
   http://issues.apache.org/jira/browse/HADOOP-1986
   http://issues.apache.org/jira/browse/HADOOP-2410

Can assignee's of 0.17 issues please backfill (or fix existing)  
release notes for their issues before we start a vote on 0.17 (next  
week or two I hope)?

Thanks,
Nige

Re: ACTION NEEDED: Hadoop 0.17 Release Notes

[Nigel Daley <nd...@yahoo-inc.com>]

On Apr 17, 2008, at 2:23 AM, Steve Loughran wrote:
> Nigel Daley wrote:
>> Hadoop Developers,
>> 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.   
>> Candidates for release notes are:
>>  - incompatibilities
>>  - features
>>  - major or critical improvements
>>  - major or critical bug fixes
>> Of the 207+ issues fixed in Hadoop 0.17, we have 68+ issues that  
>> fall into the first 3 categories above.  Of those 68, only 12 have  
>> release notes filled in.  Of those 12, only 2 are written in a  
>> user facing way (ie. no additional knowledge of the issue needed,  
>> described the impact, etc.)
>
> Interesting. In the SmartFrog JIRA we have a compatibility field  
> which gives a list of options as to how a change breaks  
> compatibility: none/unknown/new feature/incompatible at source/ 
> incompatible at deployment descriptor/breaks builds & tests
>
> with a scale of incompatibility you can present the changes in a  
> way that matters to end users (i.e. list the ones that are  
> incompatible first) rather than just the major/minor levels which  
> are just a metric of how important the team thought the change was.  
> Having that and release notes would be very good.

Very interesting.

> How do you get the release notes from jira? Is that automated?

It will be automated.

Nige

Re: ACTION NEEDED: Hadoop 0.17 Release Notes

[Steve Loughran <st...@apache.org>]

Nigel Daley wrote:
> Hadoop Developers,
> 
> 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.  Candidates for 
> release notes are:
>  - incompatibilities
>  - features
>  - major or critical improvements
>  - major or critical bug fixes
> Of the 207+ issues fixed in Hadoop 0.17, we have 68+ issues that fall 
> into the first 3 categories above.  Of those 68, only 12 have release 
> notes filled in.  Of those 12, only 2 are written in a user facing way 
> (ie. no additional knowledge of the issue needed, described the impact, 
> etc.)

Interesting. In the SmartFrog JIRA we have a compatibility field which 
gives a list of options as to how a change breaks compatibility: 
none/unknown/new feature/incompatible at source/incompatible at 
deployment descriptor/breaks builds & tests

with a scale of incompatibility you can present the changes in a way 
that matters to end users (i.e. list the ones that are incompatible 
first) rather than just the major/minor levels which are just a metric 
of how important the team thought the change was. Having that and 
release notes would be very good.

How do you get the release notes from jira? Is that automated?


-- 
Steve Loughran                  http://www.1060.org/blogxter/publish/5
Author: Ant in Action           http://antbook.org/

Re: ACTION NEEDED: Hadoop 0.17 Release Notes

[Doug Cutting <cu...@apache.org>]

Nigel Daley wrote:
> 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.

Can't we put a section at the top for "significant" changes?

> Umm, I was planning to build the release note doc and check it into the 
> release.

Okay.  I guess that works.  Then folks can review it to see that all 
"significant" changes are included.  But it seems like it might be 
easier to build this in subversion as the changes accrue.

Couldn't you draft this now, with placeholders for all the issues that 
you think are significant, then ask folks to help fill it in in 
subversion?  You could even put it at the top of CHANGES.txt!

Anyway, I'll shut up again.

Doug

Re: ACTION NEEDED: Hadoop 0.17 Release Notes

[Nigel Daley <nd...@yahoo-inc.com>]

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.

Re: ACTION NEEDED: Hadoop 0.17 Release Notes

[Doug Cutting <cu...@apache.org>]

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

Re: ACTION NEEDED: Hadoop 0.17 Release Notes

[Nigel Daley <nd...@yahoo-inc.com>]

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

Re: ACTION NEEDED: Hadoop 0.17 Release Notes

[Doug Cutting <cu...@apache.org>]

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

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.

3. Jira release notes.  See (2), above.

Is that right?  Or is there some critical difference between (2) and 
(3)?  Or do you expect (2) to be more like (1)?

Doug

Re: ACTION NEEDED: Hadoop 0.17 Release Notes

[Nigel Daley <nd...@yahoo-inc.com>]

Some more thoughts on this...

Keep in mind when writing the release notes that the text from each  
release note field will be concatenated together to form a document.  
In general, a release note should state (using past verb tense) what  
changed in this release and then what actions (if any) the user must  
take.

An example of a release note that needs some rework:
   "Decreases the frequency of logging from streaming from every 100  
records to every 10,000 records."
could be better stated as:
   "The frequency of logging in Hadoop streaming was decreased from  
every 100 records to every 10,000 records."

Another example:
   "Changes the signature of UTF8ByteArrayUtils.readLIne(InputStream)  
to UTF8ByteArrayUtils.readLIne(LineReader, Text)"
could be better stated as:
   "The signature of the public  
org.apache.hadoop.streaming.UTF8ByteArrayUtils.readLIne(InputStream)  
method was changed to UTF8ByteArrayUtils.readLIne(LineReader, Text).   
Since the old signature was not deprecated, any code using the old  
method must be changed to use the new method."

Nige

On Apr 16, 2008, at 3:38 PM, Nigel Daley wrote:
> Hadoop Developers,
>
> 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.   
> Candidates for release notes are:
>  - incompatibilities
>  - features
>  - major or critical improvements
>  - major or critical bug fixes
> Of the 207+ issues fixed in Hadoop 0.17, we have 68+ issues that  
> fall into the first 3 categories above.  Of those 68, only 12 have  
> release notes filled in.  Of those 12, only 2 are written in a user  
> facing way (ie. no additional knowledge of the issue needed,  
> described the impact, etc.)
>
> IMHO, these 2 issues have exemplary release notes which I suggest  
> you read:
>   http://issues.apache.org/jira/browse/HADOOP-1986
>   http://issues.apache.org/jira/browse/HADOOP-2410
>
> Can assignee's of 0.17 issues please backfill (or fix existing)  
> release notes for their issues before we start a vote on 0.17 (next  
> week or two I hope)?
>
> Thanks,
> Nige