This guide provides an outline, writing style guidelines, and a document template to help you structure and write your release notes.
It is not a set of rules.
After you fork this document or copy the example template found below, feel free to remove or modify sections and syntax that aren't applicable to the release.
Users and developers
Include and display:
- title with release version number
- version release date
- table of contents
In a few paragraphs, introduce the enhancements and changes that provide the most influential benefits or affect the majority of the user base.
Then, in general terms, explain the benefit each enhancement/change has for the users.
This is not where you describe technical specifics (code examples).
Think overall themes, for example:
- This release is for all the users who have been waiting for a xyz backend.
- We've sped up the processor by three minutes!
- interfaces with all your applicances.
This section should be brief and link to other documents for users requiring more information.
If there are no release-specific installation or upgrade changes, simply provide the links to the general installation and upgrade guides.
Include information about:
- user or developer environment changes
- installation/compilation method changes
- links to installation guide, upgrade guide, and sourcecode repository
This section is for specifically describing and providing code snippets for each enhancement or change that makes this release significant.
Describe what this new enhancement or change does (its purpose/goal) and how it works.
If it provides numerous features and/or results, they can be listed.
When applicable, include:
- attribute, option, syntax, etc. names and how/when they operate
- example code
- tips or caveats
Also, provide links to related documentation or more information.
Minor features and changes can be listed. Each list item includes a one sentence description with link to further documentation/information if applicable.
The Changelog is an autogenerated, bulleted list that is included from a separate source file. Each list item states the issue number, linked to the issue tracker, and a one sentence description of the issue.
This section is structured the same way as the New and Noteworthy section.
This section is structured the same way as the New and Noteworthy section.
This section is structured the same way as the Changelog section.
Copy the template below and paste it into a new document.
# x.x.x Release Notes
Author Name _Release Date_
## Installation and Upgrade Notes
## New and Noteworthy/Highlights/What's New
### Feature 1 title
### Feature 2 title
### Feature 3 title
### Feature X title
## Additional Features and Changes/Minor Features and Changes/Other Features and Changes
* minor change
* minor change
* minor change
## Changelog
xxx issues were fixed in x.x.x.
* [Issue-#](https://) Issue title or 1 sentence description
## Deprecations
### Deprecated feature 1 title
### Deprecated feature X title
## Potential Breaking Changes
### Breaking change 1 title
### Breaking change X title
## Contributors
This release would not have been possible without contributions from the
following people:
* Contributor Name
** Contribution 1
** Contribution 2
* Contributor Name
** Contribution
## Known Problems
These issues, discovered after its release, affect x.x.x.
* [Issue-#](https://) Issue title or 1 sentence description
## Feedback and Help
If you discover errors or ommisions in the source code, documentation, or
website content, please don't hesitate to submit an issue or open a pull
request with a fix.