Skip to content

doc/design: Update the release documentation #2549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 6, 2022
Merged

doc/design: Update the release documentation #2549

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 18 additions & 84 deletions doc/design/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,111 +1,45 @@
# Steps to create a new release

## Step 0: Review the Release Milestone

If the release you plan to create corresponds with an existing [milestone](https://github.com/operator-framework/operator-lifecycle-manager/milestones/), make sure that all features have been committed. If a feature will not be added to the release be sure to remove it from the milestone.

## Step 1: Installing Requirements
The OLM project uses [GoReleaser](https://goreleaser.com/) to automatically produce multi-arch container images and release artifacts during the release process.

Ensure you have `autoconf`, `automake`, and `libtool` installed.

The following command can be used to install these packages on Fedora:

```bash
dnf install autoconf automake libtool
```
In order to create a new minor version release, simply create a new tag locally, push that tag up to the upstream repository remote, and let automation handle the rest.

## Step 2: Verify Manifests
The release automation will be responsible for producing manifest list container images, generating rendered Kubernetes manifests, and a draft release that will contain both of those attached as release artifacts.

* Make sure you have a clean workspace. `git status` should show no change(s) or untracked file.
* Make sure you pull the latest from `upstream`.
* Checkout `master` branch.
* Run `make release`
## Step 0: Review the Release Milestone

## Step 3: Bump the Version
If the release you plan to create corresponds with an existing [milestone](https://github.com/operator-framework/operator-lifecycle-manager/milestones/), make sure that all features have been committed. If a feature will not be added to the release be sure to remove it from the milestone.

* Bump the version in `OLM_VERSION` file. Make a new PR with this change only.
* Wait until the PR has been merged.
## Step 1: Setup the Release Tag

## Step 4: Setup Tag
In order to trigger the existing release automation, you need to first create a new tag locally, and push that tag up to the upstream repository remote.

If git `push` is disabled on `upstream` repository in your fork, then clone this repository so that you can push to `master` directly.
**Note**: The following steps assume that remote is named `origin`.

* Pull the latest.
* Make sure you are on `master` branch.
* Make a new tag that matches the version.
* Push tag directly to this repository.

```bash
# 0.11.0 is the bumped version.
git tag -a v0.18.0 -m "Version 0.18.0"
# v0.20.0 is the bumped version.
git tag -a v0.20.0 -m "Version 0.20.0"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not necessarily related to the scope of this PR, but... should we sign our tags? (with the --sign flag)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have any opposition towards doing that. Might be worth bubbling that up to the rest of the team to see if there are any strong objections.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm for it.


# origin remote points to operator-framework/operator-lifecycle-manager
git push origin v0.18.0
git push origin v0.20.0
```

* Confirm that new images have been built here: <https://quay.io/repository/operator-framework/olm?tab=builds>.

## Step 5: Generate Manifests

* Make sure you have a clean workspace. `git status` should show no change(s) or untracked file.
* Make sure you pull the latest from `upstream`.
* Run `make release` on `master` branch.
* Make a new PR and ensure all tests pass for merging.

Verify the following:

* The image digest in manifest file(s) matches the new tag in `quay.io`.

## Step 6: Generate Changelog

Changelogs for OLM are generated using [GitHub Changelog Generator](https://github.com/github-changelog-generator/github-changelog-generator).

You need to have `gem` installed on your workstation. Execute the following command to install `github-changelog-generator`.

```bash
gem install github_changelog_generator
```

Make sure you have a GitHub API access token. You can generate one from [tokens](https://github.com/settings/tokens)

Run the following command to generate a changelog for this release:

```bash
# <start-semver> is the previous version.
# <end-semver> is the new release you have made.
GITHUB_TOKEN="<github-api-token>"
github_changelog_generator \
-u operator-framework \
-p operator-lifecycle-manager \
--token=${GITHUB_TOKEN} \
--since-tag=<start-semver> \
--future-release=<end-semver> \
--pr-label="**Other changes:**" \
-b CHANGELOG.md
```

**Note**: You may run into API rate limiting when attempting to generate the changelog.

By default, all open and closed issues will be queried when running the above command, which can lead to API rate limiting. Lower the number of issues that will be queried by specifying the `--max-issues` flag (e.g. `--max-issues=100`) and re-run the above command with that flag provided.

Ensure the `CHANGELOG.md` has been modified locally and open a PR with those generated changes.

## Step 7: Create a New GitHub Release
## Step 2: Verify that GoReleaser is Running

* Create a new GtiHub release [here](https://github.com/operator-framework/operator-lifecycle-manager/releases/new)
* Choose the new tag matching the version you created.
* You can set `Title` to the same value as the tag name.
* Add the generated `changelog` to the release description.
* Save `draft` of the release.
Once a manual tag has been created, monitor the progress of the [release workflow action](https://github.com/operator-framework/operator-lifecycle-manager/actions/workflows/goreleaser.yaml) that was triggered when a new tag has been created to ensure a successful run.

## Step 8: QuickStart
Once successful, navigate to the [quay.io/operator-framework/olm image repository](https://quay.io/repository/operator-framework/olm?tab=tags) and ensure that a new manifest list container image has been created.

Edit the GitHub Release:
## Step 3: CHANGELOG Verification

* Upload the files `crds.yam`, `install.sh` and `olm.yaml` as release artifacts. These files are located in `deploy/upstream/quickstart`
* Add install instruction, see an [example here](https://github.com/operator-framework/operator-lifecycle-manager/releases/tag/0.10.0#Install).
Navigate to the [releases](https://github.com/operator-framework/operator-lifecycle-manager/releases) tab for the OLM repository, and verify that a draft release has been produced and the generated CHANGELOG appears to be correct. GoReleaser is responsible for generating a CHANGELOG based on the diff between the latest tag, and the tag that was just created, excluding some commit(s) that have a `doc` or `test` prefix.

## Step 9: Publish Release
## Step 4: Publish the Draft Release

* Ensure that all links are valid and works as expected.
* Publish the release!
* Publish the draft release!