32 lines
2.6 KiB
Plaintext
32 lines
2.6 KiB
Plaintext
Subject: How to write the release notes
|
|
To: James
|
|
cc: Sannella.pa
|
|
|
|
How to write a release note for a fixed AR:
|
|
|
|
When an AR is fixed, it is important to write a release note for the AR, even if it is just a note saying "Release Note: none needed". There is no better time to do this than when the problem is still fresh in your mind. And there is no better person to do this than the implementer, who knows exactly how important the AR fix is.
|
|
|
|
Does this AR affect the next release? There are some ARs which are created and closed during the course of development. However, it is hard to tell just from the text of the AR. It is important to put this information in the AR, so the Release master can tell that it shouldn't be collected. The note "Release Note: Don't release -- development bug" is better than nothing.
|
|
|
|
Does this AR affect outside users? If an AR just affects internal users, put a release note "Release Note: Don't release -- internal info" in the AR.
|
|
|
|
If there is info in the AR that the outside users should know, compose a release note. It doesn't have to be perfect, but the implementer is in a better position to know what needs to be told than anyone else.
|
|
|
|
A single release note item should be talk about one piece of information. If a single AR contains or refers to multiple subjects, compose multiple release notes.
|
|
|
|
A release note contains a title, telling the substance of the item. Like AR subjects, the release note title should be short and as informative as possible (think of newspaper headlines). Include as many keywords as possible. For example "* New window functions: FOOBAR, BAZ" is better than "* New window functionality". When documenting bug fixes, try to make the titles "positive", saying "* FOOBAR arguments interpreted correctly" rather than "* Bug fixed where FOOBAR ignored argument".
|
|
|
|
When in doubt about whether a bug fix or new feature is worth documenting in the release notes, please document it. It is a lot easier for the release master to throw away information than to write it from scratch.
|
|
|
|
-----
|
|
|
|
|
|
How to assemble individual items into the "Release Notes":
|
|
|
|
If the individual release note items have been written, the primary job is to sort them by subject and importance, and assemble the big document.
|
|
|
|
For the Harmony release, the "topics" were ordered loosely on the importance of the different areas for that release (a lot of changes were made to I/O, fonts, printing, so they came first). This order is not sacred.
|
|
|
|
Within each topic area, the items are sorted by importance to the user, a subjective decision. Major new functionality, and incompatible changes obviously want to come first.
|
|
|