Release notes should always accompany your merge request. Release notes may include the following information:
- a description of any known issues;
- upcoming features;
- work in progress;
- work completed;
- reference links to issues addressed; and
- deployment instructions.
Imagine the merge request is the only communication that goes with your code delivery. Your release notes should be clear enough for the recipient to be able to understand, review, deploy, test and evaluate your work.
Release notes should:
- explain what is being delivered and how it works;
- explain how to install and enable it;
- identify any known issues, pitfalls or bugs;
- explain how to verify that it's working correctly; and
- include any special notes, considerations, etc.
Who reviews release notes?
Consider the different audiences that will use this information.
eServices
We review merge request documentation to understand what's in the package. This helps us get an idea of what to expect when it's deployed.
Code reviewer
The person reviewing the code will rely on this documentation so they understand the context of the work you've submitted. The documentation helps clarify constraints, rationale and other considerations around the implementation.
Deployers
Deployers rely on this information so they know how to enable the product and so they can confirm it's working.
Service owner
The service owner uses this documentation so they know what features to review, test, or focus on. It helps them understand the scope of features being delivered.