Beautiful, minimalist, and responsive release notes in the browser. See demo here.
Current version: 1.0.0
Lead Maintainer: Halim Qarroum
npm install --save release-note
Release notes are documents that are distributed with software products, sometimes when the product is still in the development or test state (e.g., a beta release). For products that have already been in use by clients, the release note is delivered to the customer when an update is released. - Wikipedia
I actually use this format for communicating with third-party developers or clients about the changes involved in each version of the software I deliver, and I find it interesting to share it with anyone interested. The main reasons I use this release note format is :
I find it to be very user-friendly, and radically changes the perception of the ugly-and-hard-to-read release note found in the middle of a project.
I like to separate components associated with the delivery with the actual project and its source when it is possible.
Using an HTML rich document makes it also possible to embed a lot more semantic elements (both syntaxically and graphically) in the document to give more sense out of each release.
This document does not rely on third-party resources and can be consulted offline, meaning that it does not require an Internet connectivity to be viewable. This comes in handy when the document is embedded in an application (desktop or mobile), or even on an embedded device.
This format is not suited for every use-case though, especially when an existing solution is available on the project/platform you are woking on/with. For instance using this format with open-source projects on Github may seem overkill since a single
CHANGELOG.md might suffice.
The main guidelines I apply to my self when editing the document are akin to those documented on Keep a Changelog. The most important being :
YYYY-MM-DDformat. It’s international, sensible, and language-independent.