3 Steps for Release Notes Which Users Will Love#

Release notes (RNs) are a specific type of documentation for software applications. No matter if you call it changelogs, announcements, or ‘what’s new’. Unfortunately, they’re often poorly maintained or missing altogether because people tend to skip over them.

However, they’re crucial not only for troubleshooting after an update. They are needed by everyone—other developers, testers, and marketing within a company, as well as customers.

What are release notes?#

Release notes are a list of changes between versions of an application or product. This list should always be sorted from newest to oldest.

The opposite of release notes are roadmaps which are lists of planned updates in future releases.

Release Notes or Changelog?#

In this post, we use both terms loosely and basically interchangeably, but there might be differences depending on the context.

All names - changelog (also spelled change log), product updates, release notes, what’s new or announcements - have the basically same meaning.

However, in a developer-centered context a “changelog” often refers to the internal changes and is maintained by developers for other developers, testers etc. Changelog is typically a CHANGELOG.md file in the project Git repository. If you track changes for internal users, you should follow best practices described in Keep a Changelog or Common Changelog standards.

While “release notes” are rather aimed for end-users and customers. Release notes are prepared by the product team, tech writers, etc. The release notes are usually a part of the documentation. If you keep both changelog and release notes, CHANGELOG.md is usually a source for release notes.

Who reads release notes?#

The listed changes be notable and important to the product users. Since release notes are typically part of the documentation, they share the same target audience: for example, end users, implementers, but not programmers. “Notable and important” here generally means visible to users. It does not refer to, for example, speed improvements, database changes, or underlying technology changes.

Regardless of the target audience, release notes are always intended for humans. There is no need to maintain any machine-readable format.

Why not generate release notes from Git?#

Using Git commit log to automatically produce release notes is not a good idea because Git history often contains irrelevant noise, such as merge commits and obscure titles, making them unsuitable for direct use as source for product updates.

While Git is intended to document individual source code changes, release notes should focus on summarizing significant differences across multiple commits to provide clear communication to end users.

Step 1: Collect changes#

Constitute a process on how you will communicate changes in upcoming release from idea to release note’s readers. For example

  • maintain a CHANGELOG.md file in the stable Git branch

  • file an issue in your ticketing system with an rn tag.

  • keep a spreadsheet

For each release

  • track a version number (3.14.5, 2024.10 or whatever versioning scheme you use)

  • track a release date (best in ISO format YYYY-MM-DD)

  • write a short release summary. E.g., “maintenance release with bug fixes only”, “introducing support for new systems”, etc.

Tip

Release date is often more important than version. In particular, cloud (SaaS) apps users are always on the latest version, so they likely don’t care about your internal versioning.

For each change record:

  • version

  • change type (see bellow)

  • area or product part like API, web frontend, mobile app, etc.

  • one-line summary and one or two paragraph description

  • affected users. E.g., all users or only with a paid plan?

Step 2: Categorize changes#

At minimal, distinct among these change types:

  • added (new) – a brand new features

  • changed (improved) – change in existing features

  • fixed - bug fixes

  • breaking change (incompatible) – the most important ones. Example: You have “import from CSV” file capability and you changed the expected order of columns. Or, the user’s country is now required during registration.

In bigger projects, it might be useful to recognize also these change types:

  • documentation - what’s new in documentation

  • dependencies - e.g., a product will not work on Windows 10 anymore, will not support Python 3.8, etc.

  • chores - developer stuff like a different build system, file and folder layout change, etc.

  • deprecated - soon-to-be removed, i.e., feature which is planned to be removed in future and should not be used anymore, but still works. For example, old abandoned configuration key, never-used UI dialog.

  • removed - for now removed features

  • security - vulnerability fix

Step 3: Describe changes#

For each update choose a one line long title and a paragraph long description.

Keep both of them brief as possible, use clear and plain language. Even though some product updates can be very technical, your target audience might not be.

How to write a changelog title? Answer the “what’s new” question. Few examples:

  • “Brazilian Portuguese translation”

  • “Ubuntu 24 for GitHub-hosted runners is now GA”

  • “End of life for Actions Node16”

  • “Enhanced billing platform for enterprises”

  • “New commit details page (public beta)”

  • “Portfolio summary report”

In a description, if necessary, tell details what has been changed, and try to explain what happens from the user’s perspective. Examples:

  • “XYZ is now supported on Linux. A couple of remaining stdlib deprecations will be addressed in 4.0.”

  • “New export to PDF under File menu provides a quick summary and status of key metrics.”

  • “Less worries! Changes to your document are now automatically saved as you type.”

  • “We are terminating support of Node.js 16 because it reached its end-of-life as per Node.js release policy.”

Tip

Where possible, attach links to details like pull request, documentation, blog post or rationale.

Comments

comments powered by Disqus