From 45a561e79f3cb1886f9e9d02d2dcf7d9c3e5b3ff Mon Sep 17 00:00:00 2001 From: Isaac Milarsky Date: Wed, 23 Oct 2024 16:44:08 -0500 Subject: [PATCH] add release guidelines Signed-off-by: Isaac Milarsky --- outbound/release-guidelines.md | 223 +++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 outbound/release-guidelines.md diff --git a/outbound/release-guidelines.md b/outbound/release-guidelines.md new file mode 100644 index 0000000..c8b5537 --- /dev/null +++ b/outbound/release-guidelines.md @@ -0,0 +1,223 @@ + +# 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. + +## Table of Contents + +* [Versioning](#versioning) + * [Breaking vs. non-breaking changes](#breaking-vs-non-breaking-changes) + * [Ongoing version support](#ongoing-version-support) +* [Release Process](#release-process) + * [Goals](#goals) + * [Schedule](#schedule) + * [Communication and Workflow](#communication-and-workflow) +* [Preparing a Release Candidate](#preparing-a-release-candidate) + * [Incorporating feedback from review](#incorporating-feedback-from-review) +* [Making a Release](#making-a-release) +* [Auto Changelog](#auto-changelog) +* [Hotfix Releases](#hotfix-releases) + +## Versioning + +It is best practice to use [Semantic Versioning](https://semver.org/). 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`](https://git-scm.com/book/en/v2/Git-Basics-Tagging) 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. + + +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`: + + ```bash + 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: + + ```bash + 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](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release): + + ```md + 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](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) from there: + +```bash +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: + +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](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) 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: + +```yml +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. + +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: + + ```bash + 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: + + ```bash + git fetch + git checkout 0.3.x + git tag 0.3.3 + git push --tags + ``` + +4. Create a [GitHub Release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) from this tag and the support branch. For example if `0.3.3` is the new hotfix version: + + ```md + 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 + ``` + +