Skip to content

Commit

Permalink
contrib: update release guide with helm/ansible operator and website …
Browse files Browse the repository at this point in the history 
…info (#3383)
  • Loading branch information
Eric Stroczynski authored Jul 15, 2020
1 parent 4d8960c commit 60d7572
Show file tree
Hide file tree
Showing 2 changed files with 120 additions and 83 deletions.
12 changes: 10 additions & 2 deletions website/content/en/docs/contribution-guidelines/backport-policy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,14 @@ title: Backport Policy
weight: 30
---

Usually, only very critical issues are backported. Also, it is just done to the most recent release. This can be discussed and decided during the weekly Triage meeting. For further information about how to contact the team and attending the meetings, check the [community](https://github.com/operator-framework/community) repository.
Mainly critical issue fixes are backported to the most recent minor release.
Special backport requests can be discussed during the weekly Triage meeting; this does not guarantee an exceptional backport will be created.
Occasionally non-critical issue fixes will be backported, either at an approver's discretion or by request as noted above.
For information on contacting maintainers and attending meetings, check the [community](https://github.com/operator-framework/community) repository.

Note that, if maintainers run across backport-able issues while working, it is possible to immediately decide to backport it. And then, the process would be to track the issue in the repository, and to do two pull requests with the fix. One should be made against the master branch, and the other should be a cherry-pick against the most recent release branch, where it will be backported.
## Process

Typically an issue will be fixed in the `master` branch, which will then be cherry-picked to the most recent release's branch.
Those with approver permissions and above can create a cherry-pick PR, assuming no conflicts, by commenting `/cherry-pick <release branch>`
in the PR fixing the issue in master. Fixes that are only relevant to a specific release branch can be made against
that branch directly.
191 changes: 110 additions & 81 deletions website/content/en/docs/contribution-guidelines/release.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,10 @@ Making an Operator SDK release involves:
- Tagging and signing a git commit and pushing the tag to GitHub.
- Building a release binary and signing the binary
- Creating a release by uploading binary, signature, and `CHANGELOG.md` updates for the release to GitHub.
- Creating a patch version branch of the form `v1.2.x` for major and minor releases.
- Creating a release branch of the form `v1.2.x` for each major and minor release.

Releases can only be performed by [maintainers][doc-maintainers].
Release steps can be found [below](#release-steps). If you have not run a release before we recommend reading
through the sections directly following this one.

## Dependency and platform support

Expand All @@ -27,7 +28,7 @@ As the Operator SDK interacts directly with the Kubernetes API, certain API feat

Release binaries will be built for the `x86_64` architecture for MacOS Darwin platform and for the following GNU Linux architectures: `x86_64`, `ppc64le`, `s390x`.

Base images for ansible-operator, helm-operator, scorecard-proxy, and scorecard-test will be built for the following GNU Linux architectures: `x86_64`, `ppc64le`, `s390x`.
Base images for ansible-operator, helm-operator, and scorecard-test will be built for the following GNU Linux architectures: `x86_64`, `ppc64le`, `s390x`.

Support for the Windows platform is not on the roadmap at this time.

Expand All @@ -43,7 +44,7 @@ Make sure you've [uploaded your GPG key][link-github-gpg-key-upload] and configu

**Note:** the email the key is issued for must be the email you use for git.

```bash
```sh
$ git config [--global] user.signingkey "$GPG_KEY_ID"
$ git config [--global] user.email "$GPG_EMAIL"
```
Expand All @@ -57,32 +58,65 @@ default-key $GPG_KEY_ID
**NOTE** If you do a release from an OSX machine, you need to configure `gnu-gpg` to sign the release's tag:
- Install the requirements by running: `brew install gpg2 gnupg pinentry-mac`
- Append the following to your ~/.bash_profile or ~/.bashrc or ~/.zshrc
```
```sh
export GPG_TTY=`tty`
```
- Restart your Terminal or source your ~/.\*rc file
- Then, make sure git uses gpg2 and not gpg
```bash
```sh
$ git config --global gpg.program gpg2
```
- To make sure gpg2 itself is working
```bash
```sh
$ echo "test" | gpg2 --clearsign
```

## Release branches

Each minor release has a corresponding release branch of the form `vX.Y.x`, where `X` and `Y` are the major and minor
release version numbers and the `x` is literal. This branch accepts bug fixes according to our [backport policy][backports].

This branch must be created before the release occurs to appease the Netlify website configuration demons.
You can do so by running the following before proceeding with the release, assuming the upstream SDK is the `origin` remote repo:

```sh
$ git checkout master
$ git pull
$ git checkout -b v1.3.x
$ git push -u origin v1.3.x
```

After the minor release is made, this branch must be fast-forwarded to that release's tag and a post-release PR made
against this branch. See the [release process](#4-create-a-pr-for-post-release-version-updates) for more details.

#### Cherry-picking

Once a minor release is complete, bug fixes can be merged into the release branch for the next patch release.
Fixes can be added automatically by posting a `/cherry-pick v1.3.x` comment in the `master` PR, or manually by running:

```sh
$ git checkout v1.3.x
$ git checkout -b cherrypick/some-bug
$ git cherry-pick "$GIT_COMMIT_HASH" # Hash of the merge commit to master.
$ git push origin cherrypick/some-bug
```

Create and merge a PR from your branch to `v1.3.x`.

## GitHub release information

### Locking down branches

Once a release PR has been made and all tests pass, the SDK's `master` branch should be locked so commits cannot happen between the release PR and release tag push. To lock down `master`:
Once a release PR has been made and all tests pass, the SDK's `master` branch, or [release branch](#release-branches) for patch releases,
should be locked so commits cannot happen between the release PR and release tag push. To lock down a branch:

1. Go to `Settings -> Branches` in the SDK repo.
1. Under `Branch protection rules`, click `Edit` on the `master` rule.
1. Under `Branch protection rules`, click `Edit` on the `master` or release branches rule.
1. In section `Protect matching branches` of the `Rule settings` box, increase the number of required approving reviewers to its maximum allowed value.

Now only administrators (maintainers) should be able to force merge PRs. Make sure everyone in the relevant Slack channel is aware of the release so they do not force merge by accident.

Unlock `master` after the release has completed (after step 3 is complete) by changing the number of required approving reviewers back to 1.
Unlock `master` or release branch after the release has completed (after step 3 is complete) by changing the number of required approving reviewers back to 1.

### Releasing

Expand Down Expand Up @@ -177,24 +211,16 @@ To verify a release binary using the provided asc files see the [installation gu

## Release steps

These steps describe how to conduct a release of the SDK, upgrading from `v1.2.0` to `v1.3.0`. Replace these versions with the current and new version you are releasing, respectively.

**Note:** `master` should be frozen between steps 1 and 3 so that all commits will be either in the new release or have a pre-release version, ex. `v1.2.0+git`. Otherwise commits might be built into a release that shouldn't or have an incorrect version, which makes debugging user issues difficult.

### (Patch release only) Cherry-picking to a release branch

As more than one patch may be created per minor release, branch names of the form `v1.3.x` are created after a minor version is released. Bug fixes will be merged into the release branch only after testing.
These steps describe how to conduct a release of the SDK, upgrading from `v1.2.0` to `v1.3.0`.
Replace these versions with the current and new version you are releasing, respectively.

Add fixes to the release branch by doing the following:

```bash
$ git checkout v1.3.x
$ git checkout -b release-v1.3.1
$ git cherry-pick "$GIT_COMMIT_HASH" # Usually from master
$ git push origin release-v1.3.1
```
For major and minor releases, `master` should be locked between steps 1 and 3 so that all commits will be either in the new release
or have a pre-release version, ex. `v1.2.0+git`. Otherwise commits might be built into a release that shouldn't be.
For patch releases, ensure all required bugs are [cherry-picked](#cherry-picking), then the release branch `v1.3.x` should be locked down.

Create a PR from `release-v1.3.1` to `v1.3.x`. Once CI passes and your PR is merged, continue to step 1.
**Important:** ensure a release branch-to-subdomain mapping exists in the SDK's Netlify configuration _prior to creating a release_,
ex. `v1.3.x` to `https://v1-3-x.sdk.operatorframework.io`. You can ping SDK [approvers][doc-owners] to ensure a
[release branch](#release-branches) is created prior to the release and that this mapping is created.

### 1. Create a PR for release version, CHANGELOG.md, and migration guide updates

Expand Down Expand Up @@ -234,26 +260,46 @@ Commit the following changes:
- `CHANGELOG.md`: commit changes (updated by changelog generation).
- `website/content/en/docs/migration/v1.3.0.md`: commit changes (created by changelog generation).
- `changelog/fragments/*`: commit deleted fragment files (deleted by changelog generation).
- **(Major and minor releases only)** `website/config.toml`: update `version_menu = "Releases"` with the patch-less version string `version_menu = "v1.3"`,
and add the following lines under `[[params.versions]]` for `master`:
```toml
[[params.versions]]
version = "v1.3"
url = "https://v1-3-x.sdk.operatorframework.io"
```

_(Non-patch releases only)_ Lock down the master branch to prevent further commits between this and step 4. See [this section](#locking-down-branches) for steps to do so.
---

Create and merge a new PR for `release-v1.3.0`.
Create and merge a new PR for `release-v1.3.0`. Once this PR is merged, lock down the master or release branch
to prevent further commits between this and step 4. See [this section](#locking-down-branches) for steps to do so.

### 2. Create a release tag, binaries, and signatures

The top-level `release.sh` script will take care of verifying versions in files described in step 1, and tagging and verifying the tag, as well as building binaries and generating signatures by calling `make release`.

Prerequisites:
- [`git`][doc-git-default-key] and [`gpg`][doc-gpg-default-key] default PGP keys are set locally.
- Your PGP key is publicly available in a [public key server](#release-signing).
- _For macOS users:_ GNU `sed` and `make` which are not installed by default. Install them with
```sh
$ brew install gnu-sed make
```
then ensure they are present in your `$PATH`.

Call the script with the only argument being the new SDK version:

```sh
$ ./release.sh v1.3.0
```

**NOTE** The `./release.sh` script requires `GNU sed` and the `GNU make` instead of the default installed sed. Install them with: `brew install gnu-sed` and `brew install make`, then ensure they are present in your `$PATH`.
`operator-sdk` release binaries and signatures will be in `build/`. Both binary and signature file names contain version, architecture,
and platform information; signature file names correspond to the binary they were generated from suffixed with `.asc`.
For example, signature file `operator-sdk-v1.3.0-x86_64-apple-darwin.asc` was generated from a binary named `operator-sdk-v1.3.0-x86_64-apple-darwin`.
To verify binaries and tags, see the [verification section](#verifying-a-release).

Release binaries and signatures will be in `build/`. Both binary and signature file names contain version, architecture, and platform information; signature file names correspond to the binary they were generated from suffixed with `.asc`. For example, signature file `operator-sdk-v1.3.0-x86_64-apple-darwin.asc` was generated from a binary named `operator-sdk-v1.3.0-x86_64-apple-darwin`. To verify binaries and tags, see the [verification section](#verifying-a-release).

**Note:** you must have both [`git`][doc-git-default-key] and [`gpg`][doc-gpg-default-key] default PGP keys set locally for `release.sh` to run without error. Additionally you must add your PGP key to a [public-key-server](#release-signing).
<!-- TODO: remove when ansible/helm operator repos are created and code removed from this repo -->
`ansible-operator` and `helm-operator` release binaries and signatures are similarly built for upload so `make run`
can download them in their respective operator type projects. See [#3327](https://github.com/operator-framework/operator-sdk/issues/3327) for details.

Push tag `v1.3.0` upstream:

Expand All @@ -265,67 +311,48 @@ Once this tag passes CI, go to step 3. For more info on tagging, see the [releas

**Note:** If CI fails for some reason, you will have to revert the tagged commit, re-commit, and make a new PR.

### 3. Create a PR for post-release version updates

Check out a new branch from master (or use your `release-v1.3.0` branch) and commit the following changes:

- `version/version.go`: update `Version` to `v1.3.0+git`.
- `internal/scaffold/go_mod.go`, change the `require` line version for `github.com/operator-framework/operator-sdk` from `v1.3.0` to `master`.
- `internal/scaffold/helm/go_mod.go`: same as for `internal/scaffold/go_mod.go`.
- `internal/scaffold/ansible/go_mod.go`: same as for `internal/scaffold/go_mod.go`.

Create a new PR for this branch, targetting the `master` branch. Once this PR passes CI and is merged, `master` can be unfrozen.
### 3. Fast-forward the `latest` and release branches

If the release is for a patch version (e.g. `v1.3.1`), an identical PR should be created, targetting the `v1.3.x` branch. Once this PR passes CI and is merged, `v1.3.x` can be unfrozen.
The `latest` branch points to the latest release tag to keep the main website subdomain up-to-date.
Run the following commands to do so:

### 4. Releasing binaries, signatures, and release notes
```sh
$ git checkout latest
$ git reset --hard tags/v1.3.0
$ git push -f origin latest
```

_(Non-patch releases only)_ Unlock the master branch. See [this section](#locking-down-branches) for steps to do so.
Similarly, to update the release branch, run:

The final step is to upload binaries, their signature files, and release notes from `CHANGELOG.md` for `v1.3.0`. See [this section](#releasing) for steps to do so.
```sh
$ git checkout v1.3.x
$ git reset --hard tags/v1.3.0
$ git push -f origin v1.3.x
```

### 5. Making a new release branch
### 4. Create a PR for post-release version updates

If you have created a new major or minor release, you need to make a new branch for it. To do this, checkout the tag that you created and make a new branch that matches the version you released with `x` in the position of the patch number. For example, to make a new release branch after `v1.3.0` and push it to the repo, you would follow these steps:
Check out a new branch from `master` or release branch and commit the following changes:

```console
$ git checkout tags/v1.3.0
Note: checking out 'tags/v1.3.0'.
...
$ git checkout -b v1.3.x
Switched to a new branch 'v1.3.x'
$ git push origin v1.3.x
Total 0 (delta 0), reused 0 (delta 0)
remote:
remote: Create a pull request for 'v1.3.x' on GitHub by visiting:
remote: https://github.com/operator-framework/operator-sdk/pull/new/v1.3.x
remote:
To github.com:operator-framework/operator-sdk.git
* [new branch] v1.3.x -> v1.3.x
```
- `version/version.go`: update `Version` to `v1.3.0+git`.
- `internal/scaffold/go_mod.go`, change the `require` line version for `github.com/operator-framework/operator-sdk` from `v1.3.0` to `master`.
- `internal/scaffold/helm/go_mod.go`: same as for `internal/scaffold/go_mod.go`.
- `internal/scaffold/ansible/go_mod.go`: same as for `internal/scaffold/go_mod.go`.
- **(Major and minor releases only)** `website/config.toml`: update `version_menu = "v1.3"` to `version_menu = "Releases"`.

Now that the branch exists, you need to make the post-release PR for the new release branch. To do this, simply follow the same steps as in [step 3](#3-create-a-pr-for-post-release-version-updates) with the addition of changing the branch name in the `go.mod` scaffold from `master` to the new branch (for example, `v1.3.x`). Then, make the PR against the new branch.
---

### 6. Updating the Homebrew formula
Create a new PR for this branch targeting the `master` or release branch.

We support installing via [Homebrew][homebrew], so we need to update the operator-sdk [Homebrew formula][homebrew-formula] once the release is cut. Follow the instructions below, or for more detailed ones on the Homebrew contribution [README][homebrew-readme], to open a PR against the [repository][homebrew-repo].
### 5. Releasing binaries, signatures, and release notes

The final step is to upload binaries, their signature files, and release notes from `CHANGELOG.md` for `v1.3.0`.
See [this section](#releasing) for steps to do so.

```sh
$ docker run -t -d linuxbrew/brew:latest --name homebrew
$ docker exec --rm -it homebrew /bin/bash
# Run the following commands in the container.
$ git config --global github.name <GITHUB-USERNAME>
$ git config --global github.token <GITHUB-TOKEN>
# Replace the release version of the newly cut release.
$ export OPERATORSDKURL=https://github.com/operator-framework/operator-sdk/archive/<RELEASE-VERSION>.tar.gz
$ curl -L $OPERATORSDKURL -o operator-sdk
# Calculate the SHA256
$ export OPERATORSUM="$(sha256sum operator-sdk | cut -d ' ' -f 1)"
$ brew bump-formula-pr --strict --url=$OPERATORSDKURL --sha256=$OPERATORSUM operator-sdk
```
Unlock the `master` or release branch after the Github release is complete.
See [this section](#locking-down-branches) for steps to do so.

Note: If there were any changes made to the CLI commands, make sure to look at the existing tests, in case they need updating.
---

You've now fully released a new version of the Operator SDK. Good work! Make sure to follow the post-release steps below.

Expand All @@ -338,7 +365,7 @@ The release process for the samples repo is simple:
1. Make changes to all relevant operators (at least those referenced by SDK docs) based on API changes for the new SDK release.
1. Ensure the operators build and run as expected (see each operator's docs).
1. Once all API changes are in `master`, create a release tag locally:
```console
```sh
$ git checkout master && git pull
$ export VER="v1.3.0"
$ git tag --sign --message "Operator SDK Samples $VER" "$VER"
Expand All @@ -355,12 +382,14 @@ Add the following line to the top of the GitHub release notes for `v1.3.0`:
[install-guide]: ../../install-operator-sdk
[doc-maintainers]: https://github.com/operator-framework/operator-sdk/blob/master/MAINTAINERS
[doc-owners]: https://github.com/operator-framework/operator-sdk/blob/master/OWNERS
[doc-readme-prereqs]: ../../install-operator-sdk#prerequisites
[doc-git-default-key]:https://help.github.com/en/articles/telling-git-about-your-signing-key
[doc-gpg-default-key]:https://lists.gnupg.org/pipermail/gnupg-users/2001-September/010163.html
[link-github-gpg-key-upload]:https://github.com/settings/keys
[link-git-config-gpg-key]:https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work
[doc-changelog]: https://github.com/operator-framework/operator-sdk/blob/master/CHANGELOG.md
[backports]:/docs/contribution-guidelines/backport-policy
[release-page]:https://github.com/operator-framework/operator-sdk/releases
[homebrew]:https://brew.sh/
[homebrew-formula]:https://github.com/Homebrew/homebrew-core/blob/master/Formula/operator-sdk.rb
Expand Down

0 comments on commit 60d7572

Please sign in to comment.