Skip to content

Instantly share code, notes, and snippets.

@fmquaglia
Last active May 19, 2020 10:06
Show Gist options
  • Save fmquaglia/bc2225f88a03b1b38786fb4fb788bffe to your computer and use it in GitHub Desktop.
Save fmquaglia/bc2225f88a03b1b38786fb4fb788bffe to your computer and use it in GitHub Desktop.
Release Notes

Release Notes Guide and Template

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.

Release Notes Audience

Users and developers

Writing and style guidelines

Header

Include and display:

  • title with release version number
  • version release date
  • table of contents

Preamble

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.

Installation and Upgrade Notes

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

New and Noteworthy/Highlights/What's New

This section is for specifically describing and providing code snippets for each enhancement or change that makes this release significant.

Features/Changes

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.

Additional Features and Changes/Minor Features and Changes/Other Features and Changes

Minor features and changes can be listed. Each list item includes a one sentence description with link to further documentation/information if applicable.

Changelog

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.

Deprecations

This section is structured the same way as the New and Noteworthy section.

Potential Breaking Changes

This section is structured the same way as the New and Noteworthy section.

Known Problems

This section is structured the same way as the Changelog section.

Template

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment