Skip to content

Writing Release Documentation

Jump to bottom
Stéphane Nicoll edited this page Nov 10, 2020 · 4 revisions

Introduction

Upgrading software is not the most enjoyable task in the world so, as much as possible, you’ll want to make things easy for your users. One way you can help to do that is by writing clear release notes and changelogs and making them available in the same place across all the projects that you manage.

This document aims to provide a simple set of guidelines that you can follow if you want to provide your users with clear and consistent release information.

Release Documentation

Users typically want different types of documentation depending on the type of upgrade that they’re performing.

  • For a patch release, they’ll typically want to see a simple list of the fixes and dependency upgrades that have happened.

  • For a minor/major release, they’ll be interested in what code they need to change, what’s new, and what’s been deprecated.

In addition, if there’s a specific feature that involves significant effort on their part, they’ll probably want a dedicated migration guide.

The aim of each of these documents is to provide the information that the user needs, without overwhelming them. The documents are always provided at consistent locations, and always referred to in the same way. Namely:

  • A changelog provides a simple list of the changes that have been made. They are available under https://github.com/<owner>/<repository>/releases/tag/<version> and make use of GitHub’s releases feature.

  • The release notes provide upgrade instructions and details about new features. They are available under https://github.com/<owner>/<repository>/wiki/<Project-Name>-<Major.Minor>-Release-Notes.

  • A migration guide provides detailed instructions about how to migrate a specific feature or major version. They are available under https://github.com/<owner>/<repository>/wiki/<Project-Name>-<Name>-Migration-Guide. Links to a migration guide are also provide from the release notes.

Changelogs

A changelog provides a simple list of of all relevant issues that went into a release. They should be available under https://github.com/<owner>/<repository>/releases/tag/<version>.

You can look at Spring Boot v2.3.0 release for an example.

The changelog should include the following sections:

  • New Features

  • Bug Fixes

  • Documentation

  • Dependency Upgrades

Each item listed under a section should include a link back to the original issue.

Generating Changelogs

If you are careful about the title of your issues and the way that they are labeled then it’s completely possible to automatically generate them. The GitHub Changelog Generator can run as part of your release process to create the relevant markdown.

Issue Labels

By default, the changelog generator will look for labels that contain the following text:

  • enhancement for the "New Features" section.

  • bug or regression for the "Bug Fixes" section.

  • documentation for the "Documentation" section.

  • dependency-upgrade for the "Dependency Upgrades" section.

An exact match is not required, so it’s often a good idea to use a prefix to categorize your label types. Using a prefix of type: is recommended. For example:

  • type: enhancement

  • type: bug

  • type: regression

  • type: documentation

  • type: dependency-upgrade

  • type: task

Note
 The type: task label is useful for issues that don’t need to appear in the release notes. For example, you might use it for CI related changes.
Tip
 If you want to copy labels from an existing project you can use https://github.com/destan/github-label-manager.

Issue Titles

Issue titles are very important since they are used when release notes are generated. You should try to use a consistent style for issue titles. The form that an issue title should take depends on the type of issue. The following guidelines apply to both issues and pull requests. If necessary, the title of an issue or pull request should be updated to meet these guidelines as part of working on it.

Markdown formatting

Markdown formatting doesn’t work well in issue titles and should be avoided. This is especially true for backticks which won’t render correctly and may make the release notes look odd.

Bugs including regressions and blockers

The title should describe the problem, rather than the solution. This will hopefully make it easier for a user to find an issue when they’re looking to see if their problem has already been fixed or reported.

Enhancements

The title should describe the new functionality that has been added.

Dependency Upgrades

The title should describe the project and the new version, for example "Upgrade to Spring Framework 4.3.15".

It’s helpful to keep a common format for all dependency update log messages. By consistently using the prefix "Upgrade to", it’s easy to do git log --grep to search them. The consistent titles also allow the "Dependency Upgrades" section to be sorted alphabetically which makes them easier to scan.

Tasks

Tasks (if you use them) are less important as they’re internal. The title should describe the work that needs to be done.

Release Notes

Release Notes provide upgrade instructions, details about new features, and any new deprecations in the release. They should be available under https://github.com/<owner>/<repository>/wiki/<Project-Name>-<Major.Minor>-Release-Notes.

You can look at Spring Boot 2.3 release notes for an example.

Release Notes are hand-crafted instructions specific to minor or major release (they are not required for patch releases). They are hosted on the wiki so that they can be easily edited after the release has occurred (something that would not be possible if they were in the reference documentation).

Tip
 It’s useful to provide a link from your published reference documentation to the release notes index page on the WIKI. This will help users find release notes if they happen to start with the reference documentation.

Sections

Release Notes should contain three main sections in the following order:

  1. "Upgrading from <Project Name> <Previous Version>"

  2. "New and Noteworthy"

  3. "Deprecations in <Project Name> <Version>"

The order is intentionally designed to put the most relevant information near the top of the document.

The exact content of these sections will depend on the project, but we recommend if possible to add further sub-headings to help break up the document. Try to add subheadings in order of priority. For example, call-out any changes in core features before any of the lesser used ones.

Upgrading Section

The "Upgrading" section is designed to let the user know what they will need to do to upgrade from the previous release. This section normally covers both changes to project code, as well as impacts relating to any dependency upgrades.

The upgrading section should also list any bumps to minimum supported versions (both for libraries and language versions).

If the user is only interested in upgrading a project, it should be possible for them to skip the remaining sections of the release notes.

New and Noteworthy Section

The "New and Noteworthy" section should be used to list new and interesting features in the release. As with the other sections, it’s useful to add subheadings to this section, ordered so that the most interesting features come first.

The last heading in the section is usually "Miscellaneous" which can contain a simple list of all the smaller changes.

Deprecations Section

A lot of users will be working on projects that already contain many compiler generated warnings. As such, they won’t always notice a few more deprecation warnings when they upgrade. Having a dedicated section that collects and lists project deprecations in one place is quite useful.

The deprecations section doesn’t usually need to go into a lot of depth. It’s often better to provide details of how to migrate to new classes or methods directly in the Javadoc.

If you javadoc deprecated code using @deprecated since x.x.x in favor of …​ it’s usually pretty easy to put this section together. You can search for "@deprecated since x.x.x" in your IDE then just list the results.

Milestone and RC Release Notes

During milestone and release candidate development, it’s helpful to write dedicated notes for each release. This not only gives early consumers of the project the instructions that they need, it also helps to prevent all release notes needing to be written at the last minute.

During this phase, the https://github.com/<owner>/<repository>/wiki/<Project-Name>-<Major.Minor>-Release-Notes document should state:

"Full release notes will be available when <version> has been released. For now you can check out the release notes for the individual milestones:"

You should then provide links to the milestone and RC release notes.

Once the GA release has happened, you can replace the contents of this page with the full release notes document.

Migration Guides

Migration Guides provide detailed instructions about how to migrate a specific feature or major version. They should be available under https://github.com/<owner>/<repository>/wiki/<Project-Name>-<Name>-Migration-Guide.

Some examples for migration guides in Spring Boot are:

Migration Guides are hand-crafted instructions that can be used when the "Upgrading" section of the release notes starts to get overwhelming. This can often happen during major version upgrades, or when a significant change is made to a feature.

The contents of the Migration guide will be project specific and can vary as needed. You should always provide links to your migration guides from the project release notes.

Summary

Consistent release documentation across all projects is very valuable for users. It’s also helpful for other projects that want to provide links from their release notes to others.

If you’re setting up release notes for the first, you can follow this checklist:

  • ❏ Ensure that you have good GitHub labels applied to each issue.

  • ❏ Make sure to edit issue titles for consistency as they are fixed.

  • ❏ Attach a changelog to each release (generated with the GitHub Changelog Generator if possible).

  • ❏ Ensure that release notes are published at https://github.com/<owner>/<repository>/wiki/<Project-Name>-<Major.Minor>-Release-Notes.

Clone this wiki locally