diff --git a/website/content/en/docs/building-operators/ansible/reference/webhooks.md b/website/content/en/docs/building-operators/ansible/reference/webhooks.md index d9dbcad1584..a5bbde32e44 100644 --- a/website/content/en/docs/building-operators/ansible/reference/webhooks.md +++ b/website/content/en/docs/building-operators/ansible/reference/webhooks.md @@ -165,5 +165,5 @@ Ansible-based Operator, you must [admission-controllers]:https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/ -[validating-webhook]:https://v1-21.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#validatingwebhookconfiguration-v1-admissionregistration-k8s-io -[mutating-webhook]:https://v1-21.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#mutatingwebhookconfiguration-v1-admissionregistration-k8s-io +[validating-webhook]:https://v1-26.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#validatingwebhookconfiguration-v1-admissionregistration-k8s-io +[mutating-webhook]:https://v1-26.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#mutatingwebhookconfiguration-v1-admissionregistration-k8s-io diff --git a/website/content/en/docs/contribution-guidelines/releasing.md b/website/content/en/docs/contribution-guidelines/releasing.md index 6fc531210ac..d99123b9334 100644 --- a/website/content/en/docs/contribution-guidelines/releasing.md +++ b/website/content/en/docs/contribution-guidelines/releasing.md @@ -7,8 +7,9 @@ weight: 4 These steps describe how to conduct a release of the operator-sdk repo using example versions. Replace these versions with the current and new version you are releasing, respectively. -Table of contents: +## Table of Contents: +- [Prerequisites](#prerequisites) - [Major and minor releases](#major-and-minor-releases) - [Patch releases](#patch-releases) - [`scorecard-test-kuttl` image releases](#scorecard-test-kuttl-image-releases) @@ -16,172 +17,200 @@ Table of contents: ## Prerequisites -- [`git`](https://git-scm.com/downloads) 2.2+ -- [`make`](https://www.gnu.org/software/make/) 4.2+ -- [`sed`](https://www.gnu.org/software/sed/) 4.3+ +The following tools and permissions are needed to conduct a release of the operator-sdk repo. -##### MacOS users +### Tools -Install GNU `sed` and `make` which may not be by default: +- [`git`](https://git-scm.com/downloads): version 2.2+ +- [`make`](https://www.gnu.org/software/make/): version 4.2+ +- [`sed`](https://www.gnu.org/software/sed/): version 4.3+ -```sh -brew install gnu-sed make -``` +### Permissions -Verify that the version of `make` is higher than 4.2 using command `make --version`. +- Must be a [Netlify admin][doc-owners] +- Must be an admin on the [operator-sdk repo](https://github.com/operator-framework/operator-sdk/settings/access) -Add the gnubin directory to your PATH from your `~/.bashrc`: +### Setting Up Tools for MacOS Users -```sh -echo 'export PATH="/usr/local/opt/make/libexec/gnubin:$PATH"' >> ~/.bashrc -``` +To install the prerequisite tools on MacOS, complete the following steps: -Verify that the version of `sed` is higher than 4.3 using command `gnu-sed --version`. +1. Install GNU `sed` and `make`, which may not be installed by default: -Add the `gnubin` directory to your PATH from your `~/.bashrc`: + - ```sh + brew install gnu-sed make + ``` -```sh -echo 'export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"' >> ~/.bashrc -``` - -## Major and Minor releases - -We will use the `v1.3.0` release version in this example. +1. Verify that the version of `make` is higher than 4.2 using command `make --version`. -### Before starting +1. Add the gnubin directory for `make` to your PATH from your `~/.bashrc` +to allow you to use `gmake` as `make`: -1. **Before creating a new branch**, a [Netlify admin][doc-owners] must add `v1.13.x` - to [Branch - Deploys](https://app.netlify.com/sites/operator-sdk/settings/deploys#branches). - This will watch for this branch when there are changes on Github - (creating the branch, or adding a commit). -1. **Before creating a new branch**, kick off a new build of the [ansible-operator-base - image](https://quay.io/repository/operator-framework/ansible-operator-base) - by running the - [deploy-manual](https://github.com/operator-framework/operator-sdk/actions/workflows/deploy-manual.yml) - GitHub action. After the image is built, check the security scan - results under `Child Manifests` and merge the autogenerated PRs. -1. A release branch must be created. If you have the proper permissions, - you can do this by running the following, assuming the upstream SDK - is the `upstream` remote repo: - ```sh - git checkout master - git pull - git checkout -b v1.3.x - git push -u upstream v1.3.x - ``` -1. Make sure that the list of supported OLM versions stated in the [Overview][overview] section of SDK docs is updated. If a new version of OLM needs to be officially supported, follow the steps in [updating OLM bindata](#updating-olm-bindata) section. - -### 0. Lock the `master` branch + - ```sh + echo 'export PATH="/usr/local/opt/make/libexec/gnubin:$PATH"' >> ~/.bashrc + ``` -1. Lock down the `master` branch to prevent further commits before the release completes: - 1. Go to `Settings -> Branches` in the SDK repo. - 1. Under `Branch protection rules`, click `Edit` on the `master` branch rule. - 1. In section `Protect matching branches` of the `Rule settings` box, increase the number of required approving reviewers to 6. +1. Verify that the version of `sed` is higher than 4.3 using command `gnu-sed --version`. -### 1. Create and push a release commit +1. Add the gnubin directory for `gnu-sed` to your PATH from your `~/.bashrc` +to allow you to use `gnu-sed` as `sed`: -Create a new branch to push the release commit: + - ```sh + echo 'export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"' >> ~/.bashrc + ``` -```sh -export RELEASE_VERSION=v1.3.0 -git checkout master -git pull -git checkout -b release-$RELEASE_VERSION -``` +## Major and Minor Releases -Update the top-level [Makefile] variable `IMAGE_VERSION` -to the upcoming release tag `v1.3.0`. This variable ensures sample projects have been tagged -correctly prior to the release commit. - ```sh - sed -i -E 's/(IMAGE_VERSION = ).+/\1v1\.3\.0/g' Makefile - ``` - For MAC users command will be little different. - ```sh - gsed -i -E 's/(IMAGE_VERSION = ).+/\1v1\.3\.0/g' Makefile - ``` -Run the pre-release `make` target: +We will use the `v1.3.0` release version in this example. -```sh -make prerelease -``` +**Be sure to substitute +the version you are releasing into the provided commands.** -The following changes should be present: +To perform a major or minor release, you must perform the following actions: -- `Makefile`: IMAGE_VERSION should be modified to the upcoming release tag. (This variable ensures sampleprojects have been tagged correctly prior to the release commit.) -- `changelog/generated/v1.3.0.md`: commit changes (created by changelog generation). -- `changelog/fragments/*`: commit deleted fragment files (deleted by changelog generation). -- `website/content/en/docs/upgrading-sdk-version/v1.3.0.md`: commit changes (created by changelog generation). -- `website/config.toml`: commit changes (modified by release script). -- `testdata/*`: Generated sample code. +- Ensure a new Netlify branch is created and a new ansible-operator-base image is built +- Create a release branch and lock down the master branch +- Create and merge a PR for the release branch +- Unlock the master branch and push a release tag to it +- Perform some clean up actions and announce the new release to the community -Commit these changes and push to your remote (assuming your remote is named `origin`): +### Procedure -```sh -git add Makefile changelog website testdata -git commit -m "Release $RELEASE_VERSION" -git push -u origin release-$RELEASE_VERSION -``` +1. **Before creating a new release branch**, it is imperative to perform the following initial setup steps: + 1. In the [Branches and deploy contexts](https://app.netlify.com/sites/operator-sdk/settings/deploys#branches) + pane in Netlify, click into the Additional branches list section and add `v1.13.x`. + - This will watch the branch when there are changes on Github (creating the branch, or adding a commit). + - NOTE: You must be a [Netlify admin][doc-owners] in order to edit the branches list. + 1. Kick off a new build of the [ansible-operator-base + image](https://quay.io/repository/operator-framework/ansible-operator-base) + by running the + [deploy-manual](https://github.com/operator-framework/operator-sdk/actions/workflows/deploy-manual.yml) + GitHub action on master. + 1. After the image is built, find the image in [quay](https://quay.io/repository/operator-framework/ansible-operator-base?tab=tags) and check the security scan results under `Child Manifests` to see if there are any errors that need to be addressed. + 1. Once the security scan results have been checked and addressed as necessary, merge the autogenerated PRs created by the Github action. +1. Create a release branch by running the following, assuming the upstream SDK repo is the `upstream` remote on your machine: + + - ```sh + git checkout master + git fetch upstream master + git pull master + git checkout -b v1.3.x + git push upstream v1.3.x + ``` + +1. Make sure that the list of supported OLM versions is up to date: + 1. Identify if a new version of OLM needs to be officially supported by ensuring that the latest three releases listed on the [OLM release page](https://github.com/operator-framework/operator-lifecycle-manager/releases) are all listed as supported in the [Overview][overview] section of the SDK docs. + 1. If a new version of OLM needs to be added and an old version removed, follow the steps in the [updating OLM bindata](#updating-olm-bindata) section before moving onto the next step. -### 2. Create and merge a new PR +1. Lock down the `master` branch to prevent further commits before the release completes: + 1. Go to `Settings -> Branches` in the SDK repo. + 1. Under `Branch protection rules`, click `Edit` on the `master` branch rule. + 1. In section `Protect matching branches` of the `Rule settings` box, increase the number of required approving reviewers to 6. + 1. Scroll down to save your changes to protect the `master` branch. + +1. Create and push a release commit + 1. Create a new branch to push the release commit: + + - ```sh + export RELEASE_VERSION=v1.3.0 + git checkout master + git pull master + git checkout -b release-$RELEASE_VERSION + ``` + + 1. Update the top-level [Makefile] variable `IMAGE_VERSION` +to the upcoming release tag `v1.3.0`. This variable ensures sample projects have been tagged +correctly prior to the release commit. -Create and merge a new PR for the commit created in step 1. You can force-merge your PR to the locked-down `master` + - ```sh + sed -i -E 's/(IMAGE_VERSION = ).+/\1v1\.3\.0/g' Makefile + ``` + + If this command fails on MacOS with a warning "sed is not found", follow the step 5 in the [Setting Up Tools for MacOS Users](#setting-up-tools-for-macos-users) section to map `gsed` to `sed`. + 1. Run the pre-release `make` target: + + - ```sh + make prerelease + ``` + + The following changes should be present: + - `Makefile`: IMAGE_VERSION should be modified to the upcoming release tag. (This variable ensures sampleprojects have been tagged correctly prior to the release commit.) + - `changelog/generated/v1.3.0.md`: commit changes (created by changelog generation). + - `changelog/fragments/*`: commit deleted fragment files (deleted by changelog generation). + - `website/content/en/docs/upgrading-sdk-version/v1.3.0.md`: commit changes (created by changelog generation). + - `website/config.toml`: commit changes (modified by release script). + - `testdata/*`: Generated sample code. + 1. Commit these changes and push to your remote (assuming your remote is named `origin`): + + - ```sh + git add Makefile changelog website testdata + git commit -sm "Release $RELEASE_VERSION" + git push origin release-$RELEASE_VERSION + ``` + +1. Create and merge a new PR for the release-v1.3.0 branch created in step 5.4. + - You can force-merge your PR to the locked-down `master` if you have admin access to the operator-sdk repo, or ask an administrator to do so. - -### 3. Unlock the `master` branch - -Unlock the branch by changing the number of required approving reviewers in the `master` branch rule back to 1. - -### 4. Create and push a release tag on `master` - -Refresh your local `master` branch, tag the release PR commit, and push to the main operator-sdk repo -(assumes the remote's name is `upstream`): - -```sh -git checkout master -git pull -make tag -git push upstream refs/tags/$RELEASE_VERSION -``` - -### 5. Fast-forward the `latest` and release branches - -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: - -```sh -git checkout latest -git reset --hard refs/tags/$RELEASE_VERSION -git push -f upstream latest -``` - -Similarly, to update the release branch, run: - -```sh -git checkout v1.3.x -git reset --hard refs/tags/$RELEASE_VERSION -git push -f upstream v1.3.x -``` - -### 6. Post release steps - -- Publish the new Netlify subdomain. Assuming that the Netlify prestep - was done before the new branch was created, a new [branch - option](https://app.netlify.com/sites/operator-sdk/settings/domain#branch-subdomains) - should be visible to Netlify Admins and can be mapped to a subdomain. Please test that this subdomain - works before announcing. -- Make an [operator-framework Google Group][of-ggroup] post. -- Post to Kubernetes slack in #kubernetes-operators and #operator-sdk-dev. -- In the [GitHub milestone][gh-milestones], bump any open issues to the following release. -- Update the newly unsupported branch (1.1.x in this example) the documentation to mark it as archived. - This is done by ensuring that the following is in `website/config.toml`. This PR does not need to be - merged before the release is complete. - -```toml -version = "FIXME_1.1.x" -archived_version = true -url_latest_version = "https://sdk.operatorframework.io" -``` + - Note that the docs PR check will fail because the site isn't published yet; the PR can be merged anyways. + +1. Unlock the `master` branch + 1. Go to `Settings -> Branches` in the SDK repo. + 1. Under `Branch protection rules`, click `Edit` on the `master` branch rule. + 1. In section `Protect matching branches` of the `Rule settings` box, reduce the number of required approving reviewers back to 1. + +1. Create and push a release tag on `master` + 1. Refresh your local `master` branch, tag the release PR commit, and push to the main operator-sdk repo (assumes the remote's name is `upstream`): + + - ```sh + git checkout master + git pull master + make tag + git push upstream refs/tags/$RELEASE_VERSION + ``` + +1. Fast-forward the `latest` and release branches + 1. 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: + + - ```sh + git checkout latest + git reset --hard refs/tags/$RELEASE_VERSION + git push -f upstream latest + ``` + + 1. Similarly, to update the release branch, run: + + - ```sh + git checkout v1.3.x + git reset --hard refs/tags/$RELEASE_VERSION + git push -f upstream v1.3.x + ``` + +1. Post release steps + 1. Publish the new Netlify subdomain for version-specific docs. + 1. Assuming that the Netlify prestep was done before the new branch was created, a new [branch option](https://app.netlify.com/sites/operator-sdk/settings/domain#branch-subdomains) + should be visible to Netlify Admins under Domain management > Branch subdomains and can be mapped to a subdomain. (Note: you may have to scroll down to the bottom of the Branch subdomains section to find the branch that is ready to be mapped.) + 1. Please test that this subdomain works by going to the link in a browser. You can use the link in the second column to jump to the docs page for this release. + 1. Make an [operator-framework Google Group][of-ggroup] post. + - You can use [this post](https://groups.google.com/g/operator-framework/c/2fBHHLQOKs8/m/VAd_zd_IAwAJ) as an example. + 1. Post to Kubernetes slack in #kubernetes-operators and #operator-sdk-dev. + - You can use [this post](https://kubernetes.slack.com/archives/C017UU45SHL/p1679082546359389) as an example. + 1. Clean up the GitHub milestone + 1. In the [GitHub milestone][gh-milestones], bump any open issues to the following release. + 1. Close out the milestone. + 1. Update the newly unsupported branch documentation (1.1.x in this example)to mark it as archived. (Note that this step does not need to be merged before the release is complete.) + 1. Checkout the newly unsupported release branch: + + - ```sh + git checkout v1.1.x + ``` + + 1. Modify the `website/config.toml` file on lines 88-90 to be the following: + + - ```toml + version = "v1.1" + archived_version = true + url_latest_version = "https://sdk.operatorframework.io" + ``` ## Patch releases @@ -196,14 +225,14 @@ We will use the `v1.3.1` release version in this example. GitHub action. After the image is built, check the security scan results under `Child Manifests`. -#### 0. Lock down release branches on GitHub +### 0. Lock down release branches on GitHub 1. Lock down the `v1.3.x` branch to prevent further commits before the release completes: - 1. Go to `Settings -> Branches` in the SDK repo. - 1. Under `Branch protection rules`, click `Edit` on the `v*.` branch rule. - 1. In section `Protect matching branches` of the `Rule settings` box, increase the number of required approving reviewers to `6`. + 1. Go to `Settings -> Branches` in the SDK repo. + 1. Under `Branch protection rules`, click `Edit` on the `v*.` branch rule. + 1. In section `Protect matching branches` of the `Rule settings` box, increase the number of required approving reviewers to `6`. -#### 1. Branch +### 1. Branch Create a new branch from the release branch (v1.3.x in this example). This branch should already exist prior to cutting a patch release. @@ -214,8 +243,7 @@ git pull git checkout -b release-$RELEASE_VERSION ``` - -#### 2. Prepare the release commit +### 2. Prepare the release commit Using the version for your release as the IMAGE_VERSION, execute the following commands from the root of the project. @@ -242,13 +270,13 @@ git commit -sm "Release $RELEASE_VERSION" git push -u origin release-$RELEASE_VERSION ``` -#### 3. Create and merge Pull Request +### 3. Create and merge Pull Request - Create a pull request against the `v1.3.x` branch. - Once approving review is given, merge. You may have to unlock the branch by setting "required approving reviewers" to back to `1`. (See step 0). -#### 4. Create a release tag +### 4. Create a release tag Pull down `v1.3.x` and tag it. @@ -281,7 +309,8 @@ git push -f upstream latest **Note** In case there are non-transient errors while building the release job, you must: -1. Revert the release PR. To do so, create a PR which reverts step [2](#2-create-and-merge-a-new-pr). + +1. Revert the release PR. To do so, create a PR which reverts the patch release PR created in step [3](#3-create-and-merge-pull-request). 2. Fix what broke in the release branch. 3. Re-run the release with an incremented minor version to avoid Go module errors (ex. if v1.3.1 broke, then re-run the release as v1.3.2). Patch versions are cheap so this is not a big deal. @@ -305,19 +334,18 @@ git push upstream refs/tags/$RELEASE_VERSION The [`deploy/image-scorecard-test-kuttl`](https://github.com/operator-framework/operator-sdk/actions/workflows/deploy.yml) Action workflow will build and push this image. +## Helpful Tips and Information -## Helpful tips and information - -### Binaries and signatures +### Binaries and Signatures Binaries will be signed using our CI system's GPG key. Both binary and signature will be uploaded to the release. -### Release branches +### 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]. -##### Cherry-picking +### 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: @@ -331,25 +359,39 @@ git push upstream cherrypick/some-bug Create and merge a PR from your branch to `v1.3.x`. -### GitHub release information +### GitHub Release Information GitHub releases live under the [`Releases` tab][release-page] in the operator-sdk repo. -### Updating OLM bindata +### Updating OLM Bindata Prior to an Operator SDK release, add bindata (if required) for a new OLM version by following these steps: 1. Add the new version to the [`OLM_VERSIONS`][olm_version] variable in the Makefile. -2. Remove the *lowest* version from that variable, as `operator-sdk` only supports 3 versions at a time. +2. Remove the _lowest_ version from that variable, as `operator-sdk` only supports 3 versions at a time. 3. Run `make bindata`. -4. Update the list of supported OLM versions stated in the [`Overview`][overview] section of SDK documentation is updated. +4. Check that all files were correctly updated by running this script from the root directory of the repository: + + - ```sh + ./hack/check-olm.sh + ``` + + If the check shows that files were missed by the make target, manually edit them to add the new version and remove the obsolete version. +5. Check that the list of supported OLM versions stated in the [`Overview`][overview] section of SDK documentation is updated. +6. Add the changed files to ensure that they will be committed as part of the release commit: + + - ```sh + git add -u + ``` + +### Patch Releases in Parallel -### Patch releases in parallel: +The following should be considered when doing parallel patch releases: - - Releasing in order is nice but not worth the inconvenience. Release order affects the order on GitHub releases, and which +- Releasing in order is nice but not worth the inconvenience. Release order affects the order on GitHub releases, and which is labeled "latest release". - - Do not unlock v.* branches while other releases are in progress. Instead, have an admin do the merges. - - Release announcements should be consolidated. +- Do not unlock v.* branches while other releases are in progress. Instead, have an admin do the merges. +- Release announcements should be consolidated. [doc-owners]: https://github.com/operator-framework/operator-sdk/blob/master/OWNERS [release-page]:https://github.com/operator-framework/operator-sdk/releases @@ -358,4 +400,4 @@ Prior to an Operator SDK release, add bindata (if required) for a new OLM versio [gh-milestones]:https://github.com/operator-framework/operator-sdk/milestones [Makefile]:https://github.com/operator-framework/operator-sdk/blob/master/Makefile [olm_version]:https://github.com/operator-framework/operator-sdk/blob/6002c70fe770cdaba9ba99da72685e0e7b6b69e8/Makefile#L45 -[overview]: /docs/overview/#olm-version-compatibility +[overview]: https://github.com/operator-framework/operator-sdk/blob/master/website/content/en/docs/overview/_index.md#olm-version-compatibility