Release Guidelines

This document describes the general guidelines around how to version and create regular releases for a piece of open source software. It describes semantic versioning, GitHub releases, how to review release candidates, and more.

Versioning
- Breaking vs. non-breaking changes
- Ongoing version support
Release Process
Preparing a Release Candidate
- Incorporating feedback from review
Making a Release
Auto Changelog
Hotfix Releases

Versioning

It is best practice to use Semantic Versioning. This is the predominant standard and is what is required to automatically generate changelogs using GitHub's auto changelog tool.

Each release should be associated with a git tag of the form X.Y.Z.

Given a version number in the MAJOR.MINOR.PATCH (eg., X.Y.Z) format, here are the differences in these terms:

MAJOR version - make breaking/incompatible API changes
MINOR version - add functionality in a backwards compatible manner
PATCH version - make backwards compatible bug fixes

Breaking vs. non-breaking changes

Examples and protocol for breaking changes should be established and be organized by use-case.

Definitions for breaking changes will vary depending on the use-case and project but generally speaking if changes break standard workflows in any way then they should be put in a major version update.

These use-cases should be enumerated and ideally tests should be designed to validate that these use-cases are valid for the current state of the project. i.e. Make a list of all of the things you want the software to be able to do and write tests to validate those goals. If a change breaks these use-cases or tests then it is very likely a breaking change.

Non-breaking changes conversely are changes that do not fail any key tests for a desired use-case.

Ongoing version support

The project should ideally communicate which versions of the software are actively supported and which versions are deprecated.

The project should explain the thought process behind what versions will and won’t be supported in the future.

Release Process

The sections below define the release process itself, including timeline, roles, and communication best practices.

Goals

When creating a release structure for an open source project, each release should state the goal/purpose of the release.

Goals can be things such as:

Bug fixes
Feature updates
Security hotfixes
etc.

It is important to state the goals of each release so that users of the software can more adequately maintain its use.

Schedule

Communicate the timing of the regular release structure. For example, if you plan on creating regular releases on a weekly basis you should communicate that as well as the typical days upcoming releases will become tagged.

You should also communicate special cases such as security updates or critical bugfixes and how they would likely be released earlier than what is usually scheduled.

Communication and Workflow

The project should engage in efforts to communicate the details of the project's release schedule.

Regular update messages should be sent to proper channels whenever a new major release is created.

Communicate in the slack channels, mailing lists, or other means of pushing out release notifications.

Preparing a Release Candidate

The following steps outline the process to prepare a Release Candidate for a given project. This process makes public the intention and contents of an upcoming release, while allowing work on the next release to continue as usual in the project's dev branch.

Create a Release branch from the tip of dev named release-x.y.z, where x.y.z is the intended version of the release. This branch will be used to prepare the Release Candidate. For example, to prepare a Release Candidate for 0.5.0:
```
git fetch
git switch origin/dev
git switch -c release-0.5.0
git push -u origin release-0.5.0
```
Changes generated by the steps below should be committed to this branch later.
Create a tag like x.y.z-rcN for this Release Candidate. For example, for the first 0.5.0 Release Candidate:
```
git fetch
git switch origin/release-0.5.0
git tag 0.5.0-rc1
git push --tags
```

Publish a pre-Release in GitHub:

Tag version: [tag you just pushed]
Target: [release branch]
Release title: [X.Y.Z Release Candidate N]
Description: [copy in ReleaseNotes.md created earlier]
This is a pre-release: Check

Open a Pull Request to main from the release branch (eg. 0.5.0-rc1). This pull request is where review comments and feedback will be collected.
Conduct Review of the Pull Request that was opened.

Incorporating feedback from review

The review process may result in changes being necessary to the release candidate.

For example, if the second Release Candidate for 0.5.0 is being prepared, after committing necessary changes, create a tag on the tip of the release branch like 0.5.0-rc2 and make a new GitHub pre-Release from there:

git fetch
git switch origin/release-0.5.0
# more commits per OMF review
git tag 0.5.0-rc2
git push --tags

Repeat as-needed for subsequent Release Candidates. Note the release branch will be pushed to dev at key points in the approval process to ensure the community is working with the latest code.

Making a Release

The following steps describe how to make an approved Release Candidate:

Approved. Ensure review has been completed and approval granted.
Main. Merge the Pull Request created during the Release Candidate process to main to make the release official.
Dev. Open a Pull Request from the release branch to dev. Merge this PR to ensure any changes to the Release Candidate during the review process make their way back into dev.
Release. Publish a Release in GitHub with the following information
- Tag version: [X.Y.Z] (note this will create the tag for the main branch code when you publish the release)
- Target: main
- Release title: [X.Y.Z]
- Description: copy in Release Notes created earlier
- This is a pre-release: DO NOT check
Branch. Finally, keep the release branch and don't delete it. This allows easy access to a browsable spec.

Auto Changelog

It is recommended to use the provided auto changelog github workflow to populate the project’s CHANGELOG.md file:

name: Changelog
on:
  release:
    types:
      - created
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - name: 'Auto Generate changelog'
        uses: heinrichreimer/action-github-changelog-generator@v2.3
        with:
          token: $secrets.GITHUB_TOKEN

This provided workflow will automatically populate the CHANGELOG.md with all of the associated changes created since the last release that are included in the current release.

This workflow will be triggered when a new release is created.

If you do not wish to use automatic changelogs, you can delete the workflow and update the CHANGELOG.md file manually. Although, this is not recommended.

Hotfix Releases

In rare cases, a hotfix for a prior release may be required out-of-phase with the normal release cycle. For example, if a critical bug is discovered in the 0.3.x line after 0.4.0 has already been released.

Create a Support branch from the tag in main at which the hotfix is needed. For example if the bug was discovered in 0.3.2, create a branch from this tag:
```
git fetch
git switch 0.3.2
git switch -c 0.3.x
git push -u origin 0.3.x
```
Merge (or commit directly) the hotfix work into this branch.
Tag the support branch with the hotfix version. For example if 0.3.2 is the version being hotfixed:
```
git fetch
git switch 0.3.x
git tag 0.3.3
git push --tags
```

Create a GitHub Release from this tag and the support branch. For example if 0.3.3 is the new hotfix version:

Tag version: 0.3.3
Target: 0.3.x
Release title: 0.3.3
Description: [copy in ReleaseNotes created earlier]
This is a pre-release: DO NOT check