Release Notes Style

Release notes should only show public/user visible changes, of the form:

<Project name> <version number>
===============================
<Optional summary in 10 words or less>
* <list>
* <of>
* <changes>

The changes should be of this form: * <description> (#<issue number>) Of the following types, grouped by type, and in this order, and in the following format:

* Add/remove support ("Add/Remove support for <platform>")
* Add/remove feature ("Add/Remove <feature>")
* Fix (publicly visible) bug ("Fix <bug>")
* Change feature ("Change <feature changes>")

Changes of the same type should be ordered relative to their impact on users.

Example

Foobar 1.3.2
============
* Add support for Windows 8 (#123)
* Fix dropping signals when walking backwards (#42)
* Fix typo in help file (#1)
* Change background color to blue

What (not) to include?

• Changes visible if building from source but not in binary package? No (not publicly visible)
• New bugs introduced? No (philosophical issue)
• No publicly visible changes? Don't make a release
• Refactors? No
• Wiki changes? No

When to include a summary?

Summary is only useful if it describes the changes more succinctly, and with minimal loss of accuracy, than the list of changes, so omit the summary by default. Summary should only be included if all of the following apply:

• Vast majority of changes have to do with a common "theme" (no loss of accuracy)
• 5 changes or more (faster to read summary)
• Summary is 10 words or less

What's in a summary "theme"?

A summary theme is a set of closely related features that affect a set of closely related users in a similar fashion. If the changes are over unrelated features that affect a single group of users, it is not a good theme. If the changes affect unrelated users differently, it is not a good theme. Examples:

• Fix numerous memory bugs (not good unless it affects all users equally)
• Fix numerous memory bugs under Windows (better; not good unless vast majority of Windows users affected)
• Fix numerous memory bugs under Windows 7 and 8 (good)