Release notes and change log

Release notes describe and list the changes of a product release, published to the public of users and customers of a software product.

Definition of release note

According to wikipedia, 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.

Why do I need to publish release notes?

Customers, users and the IT department of your product are interested about the latest changes, bugfixes and new features that are shipped with each new release of your software or application.

Categories of release notes

Release notes can be categorized into

• internal (e.g. used for testing, operations, support and other teams) and external release notes (customer facing)
• type of release – major release providing a lot of new features, minor release only containing some small improvements and bug fixes, and hotfix (only fixing a critical, productive issue)
• by platform – e.g. a separate (short) release note for the iOS app on the Apple AppStore, separate release notes for the Android app on the Google PlayStore and another one for the web or desktop app (since they normally ship different features and bug fixes)

How to create a release note?

Responsible for the creation of the release notes for a software project in the agile world is the product owner – or the product management or release department in the more classic, enterprise world.

The latest phase to create the release notes is, when the product is finally published, but normally it is created at the end of the development sprint or development phase.

Basically, it contains the list of tickets that are part of this release and are meant to be used by the customers. This can be extracted from tools as Microsoft Azure DevOps, Atlassian Jira or Asana.

There might be some features only for some customers to be tested on production (e.g. enabled by a feature flag), they will not be mentioned in the release notes.

The list of tickets or issues that are incorporated in the release is typically grouped by ticket type (feature, user story/task, bug) and sorted by priority (what is most important to the user).

The format of each release note item can be short as a list containing only major features with a short description (3-10 words each). On the other side, the change log can be very specific, including a title, description, (internal) ticket number, link to the ticket in the ticket system and further information.

This draft version of the release notes is reviewed by the product owner or product management, and other stakeholder (support, sales, marketing, …).

Finally – if necessary – the release notes are translated into the languages that product is available into.

When the software release is published, the release notes are published too – on the product download & change log webpage, sent via email to existing users and customers.

Do not forget to inform internal teams as support, sales and marketing.

Does and doesn’t

Based on my experience, the release notes should be a short list written in simple language and as few words as possible – so that everybody understands it.

Newly introduced features should be documented during the QA phase of the release (e.g. by marketing, support, or a specific documentation person/team). So the release notes can contain a deep link to the specific feature landing page, describing it in detail – maybe with a nice video or screenshots.

The language of release notes can be sloppy – or very formal and detailed. From my side, I would use the same language as all user-facing documentation and communication. For business usage, it should be formal.

Samples of good release notes

The following software products, apps, web applications and companies provide good release notes:

• Microsoft Azure DevOps release notes – based on agile, sprint-based releases
• Atlassian Jira release notes – one of the leading provider of development & documentation software, using Confluence as platform for their product documentation
• SalesForce release notes – good example for a complex web application
• Asana release notes – one page, containing all release notes of the web application Asana, multi-language
• Mozilla Firefox releases page – well structured using major/minor/hotfix release number

Release notes template

The basic template of a (public) release note should contain the following sections:

• Version / release & build number, and/or release date
• Added public features
• Fixed public bugs

For example:

Release 1.2.3 from 2020-11-22

New features
– Attach documents to page design
– User profile redesigned

Bug Fixes
– Login error xx fixed
– Layout problem on user page fixed

Sample release note

Additional information can be added if available, as e.g.

• Download link
• Supported platforms and environments
• Prerequisites
• Removed features
• Installation & upgrade instructions

Using a single, specific release notes home page as e.g. yourcompany.com/product/changes/ , containing the list of releases and linking to each release’s note is very helpful. The customer can bookmark the main release notes page. The website, customer support portal and social media links can point to this public change log page.

Get more information and a free release notes template .

Tools to create & manage release notes

Release notes can be created e.g. by a text editor as notepad, or a more advanced tool as e.g. Microsoft Word. It can be exported to a pdf file, so it can be read by every user. This file can be part of the release binary itself, published on the website, download page or sent via email to the product users and customers.

Customer support suites as ZenDesk and FreshDesk, or product documentation software can be used to create and maintain a specific release notes page.

There are also specific tools and products available to create, publish and manage release notes and change logs as e.g.

• Free Azure DevOps Release Notes generator – free online tool with copy/paste of work items, customizable render template and exported release notes e.g. in MarkDown format
• releasenotes.io – simple online solution to create and host release notes
• beamer – provides in-app notification for new features of a web-application
• releasenoteshub – web application, to create and publish structured release notes and changes logs
• headway – public hosted change log application, and in-product widget feature
• keepachangelog.com – incorporate change log into source code repository, when using a developer-centered documentation approach

Final words

Release notes are important and provide your customers with information about the new features and fixed bugs. They should be written in an understandable language, and kept short and brief.

If managed well, your customers will love you and your product for them. If not, customers and users will be lost, sooner or later.