Skip to content

Commit

Permalink
Initial Release Instructions
Browse files Browse the repository at this point in the history
This is an initial guide on how to release the Shipwright
operator. It provides guidance on how to create a release
candidate build with GitHub actions, and adds release
verification instructions to the OLM development guide.

Future updates to this guide will include instructions on
how to publish the new bundle to OperatorHub.

Signed-off-by: Adam Kaplan <[email protected]>
  • Loading branch information
adambkaplan committed Jun 24, 2024
1 parent a85a9b8 commit 1172f85
Show file tree
Hide file tree
Showing 3 changed files with 109 additions and 0 deletions.
5 changes: 5 additions & 0 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
24 changes: 24 additions & 0 deletions docs/development/olm-development.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
80 changes: 80 additions & 0 deletions docs/development/releasing.md
Original file line number Diff line number Diff line change
@@ -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).

0 comments on commit 1172f85

Please sign in to comment.