Skip to content

Latest commit

 

History

History
242 lines (151 loc) · 8.56 KB

release-guidelines-template.md

File metadata and controls

242 lines (151 loc) · 8.56 KB
Raw

Tier X Release Guidelines

{{ cookiecutter.project_repo_name }} will see regular updates and new releases. This document describes the general guidelines around how and when a new release is cut.

Table of Contents

Versioning

{{ cookiecutter.project_repo_name }} uses Semantic Versioning. Each release is associated with a [git tag](github.com/{{ cookiecutter.project_org }}/{{ cookiecutter.project_repo_name }}/tags) 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

Ongoing version support

Release Process

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

Goals

.

Schedule

Communication and Workflow

Preparing a Release Candidate

The following steps outline the process to prepare a Release Candidate of {{ cookiecutter.project_repo_name }}. This process makes public the intention and contents of an upcoming release, while allowing work on the next release to continue as usual in dev.

  1. 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 checkout origin/dev
git checkout -b 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.

  2. 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 checkout origin/release-0.5.0
git tag 0.5.0-rc1
git push --tags

  3. 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

  4. 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.

  5. 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 checkout 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 an official release of {{ cookiecutter.project_repo_name }}:

  1. Approved. Ensure review has been completed and approval granted.

  2. Main. Merge the Pull Request created during the Release Candidate process to main to make the release official.

  3. 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.

  4. 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

  5. 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/[email protected]
        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.

  1. 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 checkout 0.3.2
git checkout -b 0.3.x
git push -u origin 0.3.x

  2. Merge (or commit directly) the hotfix work into this branch.

  3. Tag the support branch with the hotfix version. For example if 0.3.2 is the version being hotfixed:

    git fetch
git checkout 0.3.x
git tag 0.3.3
git push --tags

  4. 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

[proj-releases-new]: https://github.com/{{ cookiecutter.project_org }}/{{ cookiecutter.project_repo_name }}/releases/new

Inspiration for this document