Mirrors
/
flux2
mirror of https://github.com/fluxcd/flux2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: link to releases spec from website

Browse Source 
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
pull/4033/head
Stefan Prodan 2 years ago
parent 5c58b45340
commit ddcabbf95d
No known key found for this signature in database
GPG Key ID: 3299AEB0E4085BAF
5 changed files with 6 additions and 753 deletions
Show Stats Download Patch File Download Diff File

11
docs/release/README.md
Unescape Escape View File

@ -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)

151
docs/release/controllers.md
Unescape Escape View File

@ -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.

145
docs/release/flux.md
Unescape Escape View File

@ -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/).

74
docs/release/packages.md
Unescape Escape View File

@ -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
```

378
docs/release/procedure.md
Unescape Escape View File

@ -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 "<module>/<semver>" "<module>/<semver>"
git push origin "<module>/<semver>"
```
In the commands above, `<module>` represents the relative path to the directory
containing the `go.mod` file, and `<semver>` 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 <feature-branch>
git tag -s -m "<module>/<semver>-<feature>.1" "<module>/<semver>-<feature>.1"
git push origin "<module>/<semver>-<feature>.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/<name>-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/<next semver>` and `<next semver>` 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/<name>-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/<next semver>` and `<next semver>` 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 <commit hash>
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/<name>-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:<release series>` (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-<pull request number>-to-v2.1.x release/v2.1.x
git cherry-pick -x <commit hash>
# Repeat the cherry-pick command for each commit to backport
git push origin backport-<pull request number>-to-v2.1.x
```
Write Preview
Loading…
Cancel
Save