A few days ago, I stumbled over an article on Opensource.com about "How to make release notes count".

The article is worth a read - it contains a number of useful suggestions on how to structure the documentation that summarizes the changes that have taken place in a software project's latest release.

Which was excellent timing, as we just merged a major overhaul of our own project's CHANGELOG file (see OP-1911 for details).

We adapted our CHANGELOG based on suggestions made by the Keep a Changelog project, with the exception of using reStructuredText for markup instead of Markdown.

To describe their impact on the project, changes are now grouped as follows:

Added for new features.
Changed for changes in existing functionality.
Deprecated for once-stable features removed in upcoming releases.
Removed for deprecated features removed in this release.
Fixed for any bug fixes.
Security to invite users to upgrade in case of vulnerabilities.

This will hopefully make it easier for our users to get an impression on the changes to expect when updating to a newer version.

How do you like the new structure? Please let us know. Thanks!

Comments