Merge pull request #223 from adambkaplan/operator-release

Initial Release Instructions

DEVELOPMENT.md

@@ -52,3 +52,8 @@ Changes that modify the `bundle` directory, however, may require the operator to
 deployed with Operator Lifecycle Manager. Refer to the
 [OLM development guide](/docs/development/olm-development.md) for instructions on how to build,
 deploy, and test the operator with OLM.
+
+## Releasing the Operator
+
+For maintainers who are asked to issue releases, please refer to the
+[release process](./docs/development/releasing.md) document.

docs/development/olm-development.md

@@ -55,6 +55,30 @@ This will run a script that does the following:
 
 Once the script completes, the Shipwright and Tekton operators will be installed on the cluster.
 
+## Testing a Release
+
+To test a release that has not been published to the Kubernetes Operators
+[OperatorHub](https://operatorhub.io/), do the following:
+
+### Step 1: Build and Push an Operator Catalog
+
+Like Step 2 above, you will need to publish a catalog containing the candidate operator release.
+Run the following command to set the correct `BUNDLE_IMG` for the catalog:
+
+```sh
+$ version=<version to test, no leading v> # example: 0.13.0-rc0
+$ make catalog-push IMAGE_REPO=<your-registry> VERSION="$version" BUNDLE_IMG="ghcr.io/shipwright-io/operator/operator-bundle:v$version"
+```
+
+### Step 2: Deploy the operator
+
+Similar to Step 3 above, deploy the operator with the catalog image:
+
+```sh
+$ version=<version to test, no leading `v`> # example: 0.13.0-rc0
+$ make catalog-run IMAGE_REPO=<your-registry> VERSION="$version"
+```
+
 ## Troubleshooting
 
 ### `sed` Command Not Found

docs/development/releasing.md

@@ -0,0 +1,80 @@
+# Release Process
+
+This document outlines the steps required to release the operator. This document assumes that you
+have achieved the "Approver"/"Maintainer" status, and have permission to manually trigger GitHub
+Actions on this repo.
+
+## Release Candidates (`X.Y.0-rcN`)
+
+### Step 0: Set Up the Release Branch
+
+Run the "Create Release Branch" GitHub Action, providing a valid Semantic Version with a major and
+minor revision number. Example: `v0.13`.
+
+### Step 1: Create a Release Candidate
+
+This is ideal for `.0` releases, where there is most risk of "blocking" bugs. Release candidates
+can be skipped for z-stream releases.
+
+Run the "Release" GitHub action, with the following parameters:
+
+- New tag: provide a semantic version _without the leading `v`_. Use a trailing `-` to add patch
+  suffix. Ex: 0.13.0-rc0.
+- Previous tag: provide a semantic version _that matches a tag on the GitHub repo_. Ex: `v0.12.0`.
+- Ref: use the branch for the release in question. Ex: `release-v0.13`.
+
+This will draft a release for GitHub - it will not publish a tag or release note.
+
+### Step 2: Publish Draft Release
+
+Find the draft release. Edit the release as follows:
+
+- Add a leading `v` suffix to the generated tag and release name. Ex: `0.13.0-rc0` becomes `v0.13.0-rc0`.
+- Change the "Draft release notes" title to "What's Changed".
+
+Once you're happy, publish the draft release note. If an item is missing from the release note,
+review the pull requests that should be included. Each desired PR should have:
+
+1. A release note.
+2. A `kind/*` label, such as `kind/feature` or `kind/bug`.
+
+### Step 3: Verify the Bundle
+
+Once the release candidate is published, broadcast the candidate build to the community in Slack
+and the shipwright-dev mailing list. Refer to the "Testing a Release" section of the
+[OLM Development](./olm-development.md#testing-a-release) guide for instructions on how to test the
+release candidate.
+
+### Step 4: Triage/Fix bugs
+
+Once the release candidate is published, the community should file any issues as bugs in GitHub. It
+is up to maintainers to determine which bugs are "release blockers" and which ones can be addressed
+in a future release.
+
+### Step 5: Repeat Release Candidates
+
+Repeat steps 1-4 as needed if a "release blocker" issue is identified.
+
+## Official Releases
+
+Before proceeding with an official release, ensure that the 
+[release branch](#step-0-set-up-the-release-branch) has been set up.
+
+### Step 1: Bump versions for release
+
+Once bugs have been triaged and the community feels ready, submit pull requests to bump the
+`VERSION` make variable. For a new release, there should be two pull requests:
+
+1. One for the `main` branch to update the minor semantic version. Ex: Update `0.12.0-rc0` to
+   `0.13.0-rc0`
+2. One for the `release-v*` branch, dropping any release candidate patch suffixes and/or updating
+   the patch semantic version itself. Ex: `0.13.0` to `0.13.1`.
+
+In both cases, run `make bundle` and commit any generated changes as part of the pull request.
+Work with the community to get these pull requests merged.
+
+### Step 2: Publish the Release
+
+Repeat the process in [Step 1](#step-1-create-a-release-candidate) and
+[Step 2](#step-2-publish-draft-release) above to create the release. For an official release, the
+version should adhere to the `X.Y.Z` format (not extra dashes).