From ddcabbf95d96a205fc1fefeddf9a8690ebe18984 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Tue, 4 Jul 2023 15:13:06 +0300 Subject: [PATCH] docs: link to releases spec from website Signed-off-by: Stefan Prodan --- docs/release/README.md | 11 +- docs/release/controllers.md | 151 -------------- docs/release/flux.md | 145 -------------- docs/release/packages.md | 74 ------- docs/release/procedure.md | 378 ------------------------------------ 5 files changed, 6 insertions(+), 753 deletions(-) delete mode 100644 docs/release/controllers.md delete mode 100644 docs/release/flux.md delete mode 100644 docs/release/packages.md delete mode 100644 docs/release/procedure.md diff --git a/docs/release/README.md b/docs/release/README.md index cfc6dac4..0faa5ad2 100644 --- a/docs/release/README.md +++ b/docs/release/README.md @@ -1,8 +1,9 @@ -# Flux Release Documentation +# Flux Dev Documentation ## Release specifications -- [Flux distribution](flux.md) -- [Flux APIs and controllers](controllers.md) -- [Flux shared libraries](packages.md) -- [Flux release procedures](procedure.md) +- [Flux distribution](https://fluxcd.io/flux/releases/) +- [Flux APIs and controllers](https://fluxcd.io/flux/releases/controllers/) +- [Flux shared packages](https://fluxcd.io/flux/releases/packages/) +- [Flux release procedures](https://fluxcd.io/flux/releases/procedure/) +- [Flux release notes template](release-notes-template.md) diff --git a/docs/release/controllers.md b/docs/release/controllers.md deleted file mode 100644 index 1459fa22..00000000 --- a/docs/release/controllers.md +++ /dev/null @@ -1,151 +0,0 @@ -# Flux controller releases - -The Flux controllers are -[Kubernetes operators](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/), -each controller has its own Git repository and release cycle (see below for details). - -Controller repositories and their interdependencies: - -1. [source-controller](https://github.com/fluxcd/source-controller) -2. [kustomize-controller](https://github.com/fluxcd/kustomize-controller) (imports `fluxcd/source-controller/api`) -3. [helm-controller](https://github.com/fluxcd/helm-controller) (imports `fluxcd/source-controller/api`) -4. [notification-controller](https://github.com/fluxcd/notification-controller) -5. [image-reflector-controller](https://github.com/fluxcd/image-reflector-controller) -6. [image-automation-controller](https://github.com/fluxcd/image-automation-controller) (imports `fluxcd/source-controller/api` and `fluxcd/image-reflector-controller/api`) - -## API versioning - -The Flux APIs (Kubernetes CRDs) follow the -[Kubernetes API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning) scheme. - -### Alpha version - -An alpha version API e.g. `v1alpha1` is considered experimental and should be used on -test environments only. - -The schema of objects may change in incompatible ways in a later API version. -The Custom Resources may require editing and re-creating after a CRD update. - -An alpha version API becomes deprecated once a subsequent alpha or beta API version is released. -A deprecated alpha version is subject to removal after a three month period. - -An alpha API is introduced when its proposal reaches the `implementable` phase in the -[Flux RFC process](https://github.com/fluxcd/flux2/tree/main/rfcs). -We encourage users to try out the alpha APIs and provide feedback -(e.g. on CNCF Slack or in the form of GitHub issues/discussions) -which is extremely valuable during early stages of development. - -### Beta version - -A beta version API e.g. `v2beta1` is considered well-tested and safe to use in production. - -The schema of objects may change in incompatible ways in a subsequent beta or stable API version. -The Custom Resources may require editing after a CRD update for which migration instructions will be -provided as part of the controller changelog. - -A beta version API becomes deprecated once a subsequent beta or stable API version is released. -A deprecated beta version is subject to removal after a six-months period. - -### Stable version - -A stable API version, e.g. `v2`, is considered feature complete. - -Any changes to the object schema do not require editing or re-creating of Custom Resources. -Schema fields can't be removed, only new fields can be added with a default value that -doesn't affect the controller's current behaviour. - -A stable API version becomes deprecated once a subsequent stable version is released. -Stable API versions are not subject to removal in any future release within a controller major version. - -In effect, this means that for as long as Flux `v2` is being maintained, all the stable API versions -will be supported. - -## Controller versioning - -The Flux controllers and their Go API packages are released by following the -[Go module version numbering](https://go.dev/doc/modules/version-numbers) conventions: - -- `vX.Y.Z-rc.W` release candidates e.g. `v1.0.0-rc.1` -- `vX.Y.Z` stable releases e.g. `v1.0.0` - -The API versioning and controller versioning are indirectly related. For example, -a source-controller minor release `v1.1.0` can introduce a new API version -`v1beta1` for a Kind `XRepository` in the `source.toolkit.fluxcd.io` group. - -### Release candidates - -Release candidates are intended for testing new features or improvements before a final release. - -In most cases, a maintainer will publish a release candidate of a controller for Flux users -to tests it on their staging clusters. Release candidates are not meant to be deployed in production -unless advised to do so by a maintainer. - -### Patch releases - -Patch releases are intended for critical bug fixes to the latest minor version, such as addressing security -vulnerabilities or fixes to severe problems with no workaround. - -Patch releases do not contain breaking changes, feature additions or any type of user-facing changes. -If a security fix requires a breaking change, then a minor release will provide the fix. - -We expect users to be running the latest patch release of a given minor release as soon as the -controller release is included in a Flux patch release. - -### Minor releases - -Minor releases are intended for backwards compatible feature additions and improvements. -Note that breaking changes may occur if required by a security vulnerability fix. - -In addition, minor releases are used when updating Kubernetes dependencies such -as `k8s.io/api` from one minor version to another. - -In effect, this means a controller minor version will be released at least every four months, after each -Kubernetes minor version release. For in-depth information about this, please refer to the -[release cadence](#release-cadence) section of this document. - -### Major releases - -Major releases are intended for drastic changes in the controller behaviour or security stance. - -A controller major release will be announced ahead of time throughout all communication channels, -and a support window of one year will be provided for the previous major version. - -## Release cadence - -Flux controllers are _at least_ released at the same rate as Kubernetes, following their cadence of three -minor releases per year. - -To properly validate the controllers against the latest Kubernetes version, -we typically allocate a time window of around two weeks for end-to-end testing of Flux controllers. -The newly released controllers offer support for Kubernetes N-2 minor versions. - -It is worth noting that in certain scenarios where project dependencies are not in sync with -the Kubernetes version or conflicts arise, this two-week timeframe may prove insufficient, -requiring additional time to address the issues appropriately. - -A Flux controller may have more than three minor releases per year, if maintainers decide to ship a -new feature or optimisation ahead of schedule. - -## Supported releases - -For Flux controllers we support the last three minor releases. - -Security fixes may be back-ported to those three minor versions as patch releases, -depending on severity and feasibility. - -Note that back-porting is provided by the community on a best-effort basis. - -## Release artifacts - -Each controller release produces the following artifacts: - -- Source code (GitHub Releases page) -- Software Bill of Materials in SPDX format (GitHub Releases page) -- SLSA provenance attestations (GitHub Releases page) -- Kubernetes manifests such as CRDs and Deployments (GitHub Releases page) -- Signed checksums of source code, SBOM and manifests (GitHub Releases page) -- Multi-arch container images (GitHub Container Registry and DockerHub) - -All the artifacts are cryptographically signed and can be verified with Cosign and GitHub OIDC. - -The release artifacts can be accessed based on the controller name and version. diff --git a/docs/release/flux.md b/docs/release/flux.md deleted file mode 100644 index c030392d..00000000 --- a/docs/release/flux.md +++ /dev/null @@ -1,145 +0,0 @@ -# Flux releases - -The Flux project repository [fluxcd/flux2](https://github.com/fluxcd/flux2) contains -the Flux command-line tool source code and the Kubernetes manifests for -bundling the [Flux controllers](controllers.md) into a distributable package. - -## Release versioning - -Flux is released by following the [semver](https://semver.org/) conventions: - -- `vX.Y.Z-rc.W` release candidates e.g. `v2.0.0-rc.1` -- `vX.Y.Z` stable releases e.g. `v2.0.0` - -The Flux project maintains release branches for the most recent three minor releases -e.g. `release/2.0.x`, `release/2.1.x` and `release/2.2.x`. - -### Release candidates - -Release candidates are intended for testing new features or improvements before a final release. - -In most cases, a maintainer will publish a release candidate for Flux users to test on their -staging clusters. Release candidates are not meant to be deployed in production unless advised -to do so by a maintainer. - -Release candidates can be unstable and they are deprecated by subsequent RC or stable versions. - -### Patch releases - -Patch releases are intended for critical bug fixes to the latest minor version, -such as addressing security vulnerabilities or fixes to severe problems with no workaround. - -Patch releases do not contain breaking changes, feature additions or any type of user-facing changes. -If a CVE fix requires a breaking change, then a minor release will provide the fix. - -We expect users to be running the latest patch release of a given minor release. - -### Minor releases - -Minor releases are intended for backward-compatible feature additions and improvements. -Note that breaking changes may occur if required by a security vulnerability fix. - -Minor releases are used when updating the Flux controllers or Kubernetes dependencies -from one minor version to another. - -In effect, this means a Flux minor version will be released at least every four months, after each -Kubernetes minor version release. For in-depth information about this, please refer to the -[release cadence](#release-cadence) section of this document. - -### Major releases - -Major releases are intended for drastic changes to the Flux behaviour or security stance. - -A Flux major release will be announced ahead of time throughout all communication channels, -and a support window of one year will be provided for the previous major version. - -## Release cadence - -Flux is _at least_ released at the same rate as Kubernetes, following their cadence of three -minor releases per year. After each Kubernetes minor release, the CLI and all controllers are -tested against the latest Kubernetes version and are released approximately two weeks after Kubernetes. -The newly released Flux version offers support for Kubernetes N-2 minor versions. - -It is worth noting that in certain scenarios where project dependencies are not in sync with -the Kubernetes version or conflicts arise, this two-week timeframe may prove insufficient, -requiring additional time to address the issues appropriately. - -Flux may have more than three minor releases per year if maintainers decide to ship a -new feature or optimization ahead of schedule. - -## Supported releases - -For Flux the CLI and its controllers, we support the last three minor releases. -Critical bug fixes, such as security fixes, may be back-ported to those three minor -versions as patch releases, depending on severity and feasibility. - -Note that back-porting is provided by the community on a best-effort basis. - -The Flux controllers are guaranteed to be compatible with each other -within one minor version (older or newer) of Flux. - -The `flux` command-line tool is supported within one minor version (older or newer) of Flux. - -## Supported upgrades - -Users can upgrade from any `v2.x` release to any other `v2.x` release (the latest patch version). - -After upgrade, [Flux Custom Resources](controllers.md#api-versioning) may require editing, -for which migration instructions are provided as part of the -[changelog](#release-changelog). - -We expect users to keep Flux up-to-date on their clusters using automation tools -such as [Flux GitHub Actions](../../action) and -[Renovatebot](https://docs.renovatebot.com/modules/manager/flux/). - -Various vendors such as Microsoft Azure, D2iQ, Weaveworks and others offer a managed Flux service, -and it's their responsibility to keep Flux up-to-date and free of CVEs. -The Flux team communicates security issues to vendors as described in the -[Coordinated Vulnerability Disclosure document](https://github.com/fluxcd/.github/blob/14b735cdb23ec80d528ff4f71e562405a2f00639/CVD_LIST.md). - -## Kubernetes supported versions - -The Flux CLI and controllers offer support for all Kubernetes versions supported upstream. - -Every Flux release undergoes a series of conformance and end-to-end tests for -the latest Kubernetes minor release. The test suite is run against -[Kubernetes Kind](https://kind.sigs.k8s.io/) for both AMD64 and ARM64 distributions. - -We expect users to keep Kubernetes up-to-date with the latest patch version of a -supported minor release. Once a Kubernetes version reaches [end-of-life](https://endoflife.date/kubernetes), -we can't guarantee the next Flux release will work with it, -as we don't run end-to-end testing for EOL Kubernetes versions. - -## Release artifacts - -Each Flux release produces the following artifacts: - -- Source code (GitHub Releases page) -- Software Bill of Materials in SPDX format (GitHub Releases page) -- SLSA provenance attestations (GitHub Releases page) -- Kubernetes manifests of all controllers (GitHub Releases page) -- CLI binaries for Linux, macOS and Windows (GitHub Releases page) -- Signed checksums of source code, SBOM and manifests (GitHub Releases page) -- Multi-arch container images of the CLI (GitHub Container Registry and DockerHub) -- OCI artifacts with the Kubernetes manifests (GitHub Container Registry and DockerHub) -- CLI [Homebrew](https://brew.sh/) formulas for Linux and macOS - -All the artifacts are cryptographically signed and can be verified with Cosign. - -The release artifacts can be accessed based on the Flux version. - -## Release changelog - -All released versions of Flux are published on [GitHub Releases page](https://github.com/fluxcd/flux2/releases) -along with a list of changes from the previous release. - -The changelog contains the following information: - -- Security vulnerabilities fixes (if any) -- Breaking changes and migration instructions (if any) -- A summary of new features and improvements for the Flux APIs and controllers -- Links to the changelog of each controller version included in a Flux release -- A list of new features, improvements and bug fixes for the Flux CLI -- A list of documentation additions - -**Note** that the vulnerability disclosure procedure is explained on the [security page](https://fluxcd.io/security/). diff --git a/docs/release/packages.md b/docs/release/packages.md deleted file mode 100644 index 66354d13..00000000 --- a/docs/release/packages.md +++ /dev/null @@ -1,74 +0,0 @@ -# Flux shared package releases - -The Go packages in [github.com/fluxcd/pkg](https://github.com/fluxcd/pkg) are dedicated Go modules, -each module has its own set of dependencies and release cycle. - -These packages are primarily meant for internal use in Flux controllers and -for projects which integrate and/or extend Flux. - -## Release versioning - -The Flux packages are released by following the -[Go module version numbering](https://go.dev/doc/modules/version-numbers) conventions: - -- `NAME/vX.Y.Z-rc.W` release candidates e.g. `runtime/v1.0.0-rc.1` -- `NAME/vX.Y.Z` stable releases e.g. `runtime/v1.0.0` - -To import or update a Flux package in a Go project: - -```shell -go get github.com/fluxcd/pkg/runtime@v1.0.0 -``` - -### Release candidates - -Release candidates are intended for testing new features or improvements. - -In most cases, a maintainer will cut a release candidate of a package to include it -in a Flux controller release candidate. - -Release candidates are not meant to be included in Flux stable releases. -Before cutting a stable release of a controller, all imported Flux packages must be pinned to a stable version. - -### Patch releases - -Patch releases are intended for critical bug fixes to the latest minor version, such as addressing security -vulnerabilities or fixes to severe problems with no workaround. - -Patch releases should not contain breaking changes, feature additions or any type of improvements. - -Patch releases should be used when updating dependencies such as `k8s.io/api` from one patch version to another. - -### Minor releases - -Minor releases are intended for backwards compatible feature additions and improvements. - -Minor releases should be used when updating dependencies such as `k8s.io/api` from one minor version to another. -If a [Kubernetes minor version](https://github.com/kubernetes/sig-release/blob/master/release-engineering/versioning.md) -upgrade requires a breaking change (e.g. removal of an API such as `PodSecurityPolicy`) in a Flux package public API, -then a major version release is necessary. - -### Major releases - -Major releases are intended for backwards incompatible feature additions and improvements. - -Any change to a package public API, such as a change to a Go function signature, requires a new major release. - -## Supported releases - -For Flux Go packages we only support the latest stable release. We expect for projects that depend on -Flux packages to stay up-to-date by automating the Go modules updates with tools like Dependabot. - -In effect, this means we'll not backport CVE fixes to an older minor or major version of a package. - -## Deprecation policy - -A Flux Go package can be deprecated at any time. Usually a deprecated package may be replaced a -different one, but there are no guarantees to always have a suitable replacement. - -A deprecated package is marked as so in its `go.mod` e.g. - -```go -// Deprecated: use github.com/fluxcd/pkg/tar instead. -module github.com/fluxcd/pkg/untar -``` diff --git a/docs/release/procedure.md b/docs/release/procedure.md deleted file mode 100644 index 084340e6..00000000 --- a/docs/release/procedure.md +++ /dev/null @@ -1,378 +0,0 @@ -# Flux release procedures - -This document provides an overview of the release procedures for each component -type in the Flux project. It is intended for project maintainers, but may also -be useful for contributors who want to understand the release process. - -If you have any questions, please reach out to another maintainer for -clarification. - -## Table of contents - -- [General rules](#general-rules) - + [Signing releases](#signing-releases) -- [Component types](#component-types) - + [Shared packages](#shared-packages) - + [Controllers](#controllers) - * [Minor releases](#controllers-minor-releases) - * [Patch releases](#controllers-patch-releases) - * [Release candidates](#controllers-release-candidates) - * [Preview releases](#controllers-preview-releases) - + [Distribution](#distribution) - * [Minor releases](#distribution-minor-releases) - * [Patch releases](#distribution-patch-releases) - * [Release candidates](#distribution-release-candidates) -- [Backport changes for patch releases](#backport-changes-for-patch-releases) - + [Manual backporting](#manual-backporting) - -## General rules - -### Signing releases - -To ensure the integrity and authenticity of releases, all releases must be -signed with a GPG key. The public key must be uploaded to the GitHub account of -the maintainer, and the private key must be kept secure. - -In addition, we recommend the following practices: - -1. Safeguard your GPG private key, preferably using a hardware security key - like a YubiKey. -2. Use a subkey dedicated to signing releases, set an expiration date for - added security, and keep the master key offline. Refer to - [this guide](https://riseup.net/en/security/message-security/openpgp/best-practices#key-configuration) - for detailed instructions. - -We understand that this may seem overwhelming. If you are not comfortable with -the process, don't hesitate to seek assistance from another maintainer who has -experience with signing releases. - -Please note that SSH signatures are not supported at this time due to limited -availability of SSH signature verification outside the `git` CLI. - -## Component types - -### Shared packages - -To release a [package](packages.md) as a project maintainer, follow these steps: - -1. Tag the `main` branch using SemVer. -2. Sign the tag according to the [general rules](#general-rules). -3. Push the signed tag to the upstream repository. - -Use the following commands as an example: - -```shell -git clone https://github.com/fluxcd/pkg.git -git switch main -git tag -s -m "/" "/" -git push origin "/" -``` - -In the commands above, `` represents the relative path to the directory -containing the `go.mod` file, and `` refers to the SemVer version of the -release. For instance, `runtime/v1.0.0` for [`fluxcd/pkg/runtime`](https://github.com/fluxcd/pkg/tree/main/runtime), -or `http/fetch/v0.1.0` for [`fluxcd/pkg/http/fetch`](https://github.com/fluxcd/pkg/tree/main/http/fetch). - -Before cutting a release candidate, ensure that the package's tests pass -successfully. - -Here's an example of releasing a candidate from a feature branch: - -```shell -git switch -git tag -s -m "/-.1" "/-.1" -git push origin "/-.1" -``` - -### Controllers - -To release a [controller](controllers.md) as a project maintainer, follow the -steps below. Note that the release procedure differs depending on the type of -release. - -##### Controllers: minor releases - -1. Checkout the `main` branch and pull changes from the remote repository. - -2. Create a "release series" branch for the next minor SemVer range, e.g., - `release/v1.2.x`, and push it to the remote repository. - - ```shell - git switch -c release/v1.2.x main - ``` - -3. From the release series branch, create a release preparation branch for the - specific release. - - ```shell - git switch -c release-v1.2.0 release/v1.2.x - ``` - -4. Add an entry to `CHANGELOG.md` for the new release and commit the changes. - - ```shell - vim CHANGELOG.md - git add CHANGELOG.md - git commit -s -m "Add changelog entry for v1.2.0" - ``` - -5. Update `github.com/fluxcd/-controller/api` version in `go.mod` and - `newTag` value in `config/manager/kustomization.yaml` to the target SemVer - (e.g., `v1.2.0`). Commit and push the changes. - - ```shell - vim go.mod - vim config/manager/kustomization.yaml - git add go.mod config/manager/kustomization.yaml - git commit -s -m "Release v1.2.0" - git push origin release-v1.2.0 - ``` - -6. Create a pull request for the release branch and merge it into the release - series branch (e.g., `release/v1.2.x`). - -7. Create `api/` and `` tags for the merge commit in - `release/v1.2.x`. Ensure the tags are signed according to the [general - rules](#general-rules), and push them to the remote repository. - - ```shell - git switch release/v1.2.x - git pull origin release/v1.2.x - git tag -s -m "api/v1.2.0" api/v1.2.0 - git push origin api/v1.2.0 - git tag -s -m "v1.2.0" v1.2.0 - git push origin v1.2.0 - ``` - -8. Confirm that the CI builds and releases the newly tagged version. - -9. Create a pull request for the release series branch and merge it into `main`. - -##### Controllers: patch releases - -1. Ensure everything to be included in the release is backported to the - "release series" branch (e.g., `release/v1.2.x`). If not, refer to the - [backporting](#backport-changes-for-patch-releases) section. - -2. From the release series branch, create a release preparation branch for the - specific patch release. - - ```shell - git pull origin release/v1.2.x - git switch -c release-v1.2.1 release/v1.2.1 - ``` - -3. Add an entry to `CHANGELOG.md` for the new release and commit the changes. - - ```shell - vim CHANGELOG.md - git add CHANGELOG.md - git commit -s -m "Add changelog entry for v1.2.1" - ``` - -4. Update `github.com/fluxcd/-controller/api` version in `go.mod` and - `newTag` value in `config/manager/kustomization.yaml` to the target SemVer - (e.g., `v1.2.1`). Commit and push the changes. - - ```shell - vim go.mod - vim config/manager/kustomization.yaml - git add go.mod config/manager/kustomization.yaml - git commit -s -m "Release v1.2.1" - git push origin release-v1.2.1 - ``` - -5. Create a pull request for the release branch and merge it into the release - series branch (e.g., `release/v1.2.x`). - -6. Create `api/` and `` tags for the merge commit in - `release/v1.2.x`. Ensure the tags are signed according to the [general - rules](#general-rules), and push them to the remote repository. - - ```shell - git switch release/v1.2.x - git pull origin release/v1.2.x - git tag -s -m "api/v1.2.1" api/v1.2.1 - git push origin api/v1.2.1 - git tag -s -m "v1.2.1" v1.2.1 - git push origin v1.2.1 - ``` - -7. Confirm that the CI builds and releases the newly tagged version. - -8. Cherry-pick the changelog entry from the release series branch and create a - pull request to merge it into `main`. - - ```shell - git pull origin main - git switch -c pick-changelog-v1.2.1 main - git cherry-pick -x - git push origin pick-changelog-v1.2.1 - ``` - -#### Controllers: release candidates - -In some cases, it may be necessary to release a [release -candidate](controllers.md#release-candidates) of a controller. - -To create a first release candidate, follow the steps to create a [minor -release](#controllers-minor-releases), but use the `rc.X` suffix for SemVer -version to release (e.g., `v1.2.0-rc.1`). - -Once the release series branch is created, subsequent release candidates and -the final (non-RC) release should follow the procedure for [patch controller -releases](#controllers-patch-releases). - -#### Controllers: preview releases - -In some cases, it may be necessary to release a preview of a controller. -A preview release is a release that is not intended for production use, but -rather to allow users to quickly test new features or an intended bug fix, and -provide feedback. - -Preview releases are made by triggering the `release` GitHub Actions workflow on -a specific Git branch. This workflow will build the container image, sign it -using Cosign, and push it to the registry. But it does not require a Git tag, -GitHub release, or a changelog entry. - -To create a preview release, follow the steps below. - -1. Navigate to `https://github.com/fluxcd/-controller/actions/workflows/release.yml`. - -2. Click the `Run workflow` button. - -3. Select the branch to release from the `Branch` dropdown. - -4. The default values for the `image tag` (`preview`) should be correct, but can - be changed if necessary. - -5. Click the green `Run workflow` button. - -6. The workflow will now run, and the container image will be pushed to the - registry. Once the workflow has completed, the image reference will be - available in the logs, and can be shared in the relevant issue or pull - request. - -### Distribution - -To release a [Flux distribution](flux.md) as a project maintainer, follow the -steps below. - -Note that the Flux distribution contains multiple components, and you may need -to release [controllers](#controllers) before releasing the distribution. -Automation is in place to automatically create a pull request to update the -version in the `main` branch when a new controller version is released. - -#### Distribution: minor releases - -1. Ensure everything to be included in the release is merged into the `main` - branch, including any controller releases you wish to include in the - release. - -2. Create a "release series" branch for the next minor SemVer range, e.g., - `release/v2.2.x`, and push it to the remote repository. - - ```shell - git switch -c release/v2.2.x main - ``` - -3. Prepare the required release notes for this release, see [release - notes](#distribution-release-notes) for more information. - -4. Tag the release series branch with the SemVer version of the release, e.g., - `v1.2.0`. Ensure the tag is signed according to the [general - rules](#general-rules), and push it to the remote repository. - - ```shell - git tag -s -m "v2.2.0" v2.2.0 - git push origin v2.2.0 - ``` - -5. Confirm that the CI builds and releases the newly tagged version. - -6. Once the release is complete, update the release notes on GitHub with the - release notes prepared in step 3. - -7. Post a message in the [`#flux` CNCF Slack channel](https://cloud-native.slack.com/archives/CLAJ40HV3) - announcing the release, and pin it. - -#### Distribution: patch releases - -1. Ensure everything to be included in the release is backported to the - "release series" branch (e.g., `release/v2.2.x`). If not, refer to the - [backporting](#backport-changes-for-patch-releases) section. - -2. Prepare the required release notes for this release, see [release - notes](#distribution-release-notes) for more information. - -3. Tag the release series branch with the SemVer version of the release, e.g., - `v2.2.1`. Ensure the tag is signed according to the [general - rules](#general-rules), and push it to the remote repository. - - ```shell - git tag -s -m "v2.2.1" v2.2.1 - git push origin v2.2.1 - ``` - -4. Confirm that the CI builds and releases the newly tagged version. - -5. Once the release is complete, update the release notes on GitHub with the - release notes prepared in step 2. - -6. Post a message in the [`#flux` CNCF Slack channel](https://cloud-native.slack.com/archives/CLAJ40HV3) - -#### Distribution: release candidates - -In some cases, it may be necessary to release a [release candidate](flux.md#release-candidates) -of the distribution. - -To create a first release candidate, follow the steps to create a [minor -release](#distribution-minor-releases), but use the `rc.X` suffix for SemVer -version to release (e.g., `v2.2.0-rc.1`). - -Once the release series branch is created, subsequent release candidates and -the final (non-RC) release should follow the procedure for [patch releases](#distribution-patch-releases). - -#### Distribution: release notes - -The release notes template for Flux distributions is available in the -[release-notes-template.md](https://github.com/fluxcd/flux2/blob/main/docs/release/release-notes-template.md) file. - -## Backport changes for patch releases - -The Flux projects have a backport bot that automates the process of backporting -changes from `main` to the release series branches. The bot is configured to -backport pull requests that are labeled with `backport:` (e.g., -`backport:release/v2.1.x`) and have been merged into `main`. - -The label(s) are preferably added to the pull request before it is merged into -`main`. If the pull request is merged into `main` without labeling, they can -still be added to the pull request after it has been merged. - -The backport bot will automatically backport the pull request to the release -series branch and create a pull request for the backport. It will comment on -the pull request with a link to the backport pull request. - -If the backport bot is unable to backport a pull request automatically (for -example, due to conflicts), it will comment on the pull request with -instructions on how to backport the pull request manually. - -### Manual backporting - -In some cases, the backport bot may not be suitable for backporting a pull -request. For example, if the pull request contains a series of changes of which -a subset should be backported. In these cases, the pull request should be -backported manually. - -To backport a pull request manually, create a new branch from the release -series branch (e.g., `release/v2.1.x`) and cherry-pick the commits from the -pull request into the new branch. Push the new branch to the remote repository -and create a pull request to merge it into the release series branch. - -```shell -git pull origin release/v2.1.x -git switch -c backport--to-v2.1.x release/v2.1.x -git cherry-pick -x -# Repeat the cherry-pick command for each commit to backport -git push origin backport--to-v2.1.x -```