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
