Release notes

Release notes describe important information about a distribution of a hardware or software product.^[1] Often, release notes accompany an update to a product that was released previously and is in use. But they may also be available for a product still in the development or being tested (e.g., a beta release).^[2][3] Release notes are typically shared with end users, customers and clients of an organization.^[4]

Alternate names used and related information includes changelog,^[5][6] release logs, software changes, revision history, updates, or README.^[7] Often release notes and changelog are published separately to allow for differentiation of feature highlights from bugs, change requests, and other improvements.^[8][9] Release notes differ from end-user license agreement, since they do not (should not) contain any legal terms of the software product or service. The focus should be on the software release itself, not for example legal conditions.^[10]

Release notes might be provided as an artifact accompanying the deliverables for system testing and system integration testing and other managed environments especially with reference to an information technology organization. Release notes can contain test results and information about the test procedure. This kind of information gives readers of the release note more confidence in the fix/change done; this information also enables implementer of the change to conduct rudimentary acceptance testing.

Release notes can describe how to install or build software, instead of highlighting new features or resolved bugs.^[11] Another term often used in this context is system requirements: the hardware and software required for installing, running or building the software.

Content

With no standards, both format and content vary. Generally, release notes are a terse summary of recent changes (not a substitute for a user guide), written in the present tense and include information such as:

Header

Document name (i.e. Release Notes), product name, release number, release date, note date, note version, etc.

Overview

A brief overview of the changes and in the absence of other documentation, the product as well.

Purpose

Describes the purpose of the document.

Issues

A list of what is new in the release, including bug fixes and new features.

Issue summary

A short description of the bug or the enhancement in the release.

Steps to reproduce

The steps that were followed when the bug was encountered.

Resolution

A short description of the modification/enhancement that was made to fix the bug.

End-user impact

What different actions are needed by end-users. This should include whether other functionality is impacted by these changes.

Support impacts

Changes required in the daily process of administering the software.

Notes

Other information such as installation, upgrades and product documentation (including documentation updates)

Disclaimers

Company and standard product related messages. e.g.; freeware, anti-piracy, duplication etc.. See also disclaimer.

Contact

Support contact information.

The Release Notes Schema Specification is a proposed specification for a release notes document.^[12]

See also

• Changelog
• Configuration management
• End-user license agreement
• README
• Release management
• Release candidate
• Software release life cycle
• SWEBOK
• Terms of service

Further reading

• Laura Moreno et al. ARENA: An Approach for the Automated Generation of Release Notes, IEEE Transactions on Software Engineering (Volume: 43, Issue: 2, Feb. 1 2017)^[13]
• Newton, Casey (February 10, 2016). "I drank beer and wrote release notes with the Medium release notes team". The Verge. Vox Media. Retrieved April 5, 2021.
• GNU coding standards - 6.8 Change Logs