Merge pull request #31 from DSACMS/add-release-guidelines

Create General Release Guidance and Put it in the Outbound Section

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/[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:
+
+	```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
+	```
+
+