Many of our peer projects generate trivial "release notes" as a list of bugs fixed, giving the bug number and one-line description, for instance as auto-generated by Jira under:
Project > Road Map (or Change Log) > Release Notes
e.g., for 0.20.205.0:
However, the Hadoop project has tried to do better than this, by actually collecting "Release Note" field values from fixed bugs (or Description fields from bugs with empty Release Note fields), and presenting them in the form of the releasenotes.html document template, e.g., for 0.20.205.0:
When doing the notes for 0.20.205.0, I found that the tool for doing these collected Release Notes (src/docs/relnotes.py) was broken in a couple of respects:
- It was inconsistent with the documented process in HowToRelease, because it wanted bug lists piped in somewhat differently.
- It assumed that Jira's report on "Resolved" bugs was sufficient, while that list often differs somewhat from CHANGES.txt. In particular, bugs held open for ports to other branches would not be reported as Resolved in the current branch.
- Most critically, the feature to extract the "Release Note" field from jira issues doesn't work unless the person running it has top-level Jira admin privs (not just admin privs for the Hadoop projects). This restriction is built in to the Jira CLI tool ('jira.sh').
I fixed these issues, and will submit the improved tool for review. It now does the following:
- Query Jira for bugs resolved in the current release.
- Query CHANGES.txt for bugs resolved in the current release.
- Merge and diff the two lists, reporting the result and giving the Release Manager an opportunity to resolve the variances.
- Look up the Release Note field for each resolved bug, scraping it from a 'curl' call rather than the admin-restricted Jira CLI tool.
- If there is no Release Note, use the Description field but limit it to the first 500 characters, in case the Description is long.
- Format as before.
I also suggest these enhancements:
- List the jiras with Release Notes first. These are usually the larger or incompatible changes that most readers will care about most. Then list the other jiras with their descriptions.
- Sort in forward numerical order, instead of reverse.