diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 66c1fba9..00000000 --- a/docs/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Flux Development Documentation - -## Release Engineering - -- [Shared packages release specifications](release/packages.md) -- [Controllers release specifications](release/controllers.md) diff --git a/docs/release/README.md b/docs/release/README.md new file mode 100644 index 00000000..3920353a --- /dev/null +++ b/docs/release/README.md @@ -0,0 +1,7 @@ +# Flux Release Documentation + +## Release specifications + +- [Flux distribution](flux.md) +- [Flux APIs and controllers](controllers.md) +- [Flux shared libraries](packages.md) diff --git a/docs/release/controllers.md b/docs/release/controllers.md index a47427ed..68d9321c 100644 --- a/docs/release/controllers.md +++ b/docs/release/controllers.md @@ -20,26 +20,27 @@ The Flux APIs (Kubernetes CRDs) follow the ### Alpha version -An alpha version API e.g. `v1alpha1` is considered experiment and should be used on +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 controller release. -The custom resources may require editing and re-creating after a CRD update. +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 months 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 which is extremely -valuable during early stages of development. +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 be used. 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 +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. @@ -49,7 +50,7 @@ A deprecated beta version is subject to removal after a six months period. A stable version API e.g. `v2` is considered feature complete. -Any changes to the object schema do not require editing or re-creating of custom resources. +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. @@ -110,9 +111,10 @@ and a support window of one year will be provided for the previous major version ## Release cadence -Flux controllers follow Kubernetes three releases per year cadence. After each Kubernetes minor release, -all controllers are tested against the latest Kubernetes version and are released at approximately two -weeks after Kubernetes. The newly released controllers offer support for Kubernetes N-2 minor versions. +Flux controllers are at least released at the same rate as Kubernetes, following their cadence of three +minor releases per year. After each Kubernetes minor release, all controllers are tested against the latest +Kubernetes version and are released at approximately two weeks after Kubernetes. +The newly released controllers offer support for Kubernetes N-2 minor versions. 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. @@ -121,9 +123,11 @@ new feature or optimisation ahead of schedule. For Flux controllers we support the last three minor releases. -Security fixes, may be backported to those three minor versions as patch 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: @@ -162,16 +166,15 @@ curl -sL https://github.com/fluxcd//releases/download/ As a project maintainer, to release a controller and its API: 1. Checkout the `main` branch and pull changes from remote. -2. Create a `api/` tag and push it to remote. -3. Create a new branch from `main` i.e. `release-`. This +2. Create a new branch from `main` i.e. `release-`. This will function as your release preparation branch. -4. Update the `github.com/fluxcd/-controller/api` version in `go.mod` -5. Add an entry to the `CHANGELOG.md` for the new release and change the +3. Update the `github.com/fluxcd/-controller/api` version in `go.mod` +4. Add an entry to the `CHANGELOG.md` for the new release and change the `newTag` value in ` config/manager/kustomization.yaml` to that of the semver release you are going to make. Commit and push your changes. -6. Create a PR for your release branch and get it merged into `main`. -7. Create a `` tag for the merge commit in `main` and - push it to remote. +5. Create a PR for your release branch and get it merged into `main`. +6. Create a `api/` tag for the merge commit in `main` and push it to remote. +7. Create a `` tag for the merge commit in `main` and push it to remote. 8. Confirm CI builds and releases the newly tagged version. **Note** that the Git tags must be cryptographically signed with your private key diff --git a/docs/release/flux.md b/docs/release/flux.md new file mode 100644 index 00000000..a5f8a3ab --- /dev/null +++ b/docs/release/flux.md @@ -0,0 +1,173 @@ +# Flux release spec + +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`, `release-2.1` and `release-2.2`. + +### 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 tests it 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 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 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 backwards 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. To properly validate the Flux CLI and controllers against +the latest Kubernetes version, we reserve a time window of at least two weeks for end-to-end testing. + +### 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 at approximately two weeks after Kubernetes. +The newly released Flux version offers support for Kubernetes N-2 minor versions. + +Flux 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 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) +- 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. + +To verify and pull the Flux CLI container image: + +```shell +cosign verify ghcr.io/fluxcd/flux-cli: +docker pull ghcr.io/fluxcd/flux-cli: +``` + +To install the latest stable release of the Flux CLI with Homebrew: + +```shell +brew install fluxcd/tap/flux +``` + +To download the Kubernetes manifests: + +```shell +cosign verify ghcr.io/fluxcd/flux-manifests: +flux pull artifact oci://ghcr.io/fluxcd/flux-manifests: --output . +``` + +## 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/). + +## Release procedure + +- `v2.X.Y-RC.Z` (Branch: `release-2.X`) + - When the `main` branch is feature-complete for `v2.X`, we will cherrypick PRs essential to `v2.X` to the `release-2.X` branch. + - We will cut the first [release candidate](#release-candidates) by tagging the `release-2.X` as `v2.X.0-RC.0`. + - If we're not satisfied with `v2.X.0-RC.0`, we'll keep releasing RCs until all issues are solved. +- `v2.X.0` (Branch: `release-2.X`) + - The final release is cut from the `release-2.X` branch and tagged as `v2.X.0`. +- `v2.X.Y, Y > 0` (Branch: `release-2.X`) + - [Patch releases](#patch-releases) are released as we cherrypick commits from `main` into the `release-2.X` branch. + - Flux controller updates (patch versions of a controller minor release included in `v2.X.0`) PRs are merged directly into the `release-2.X` branch. + - A patch release is cut from the `release-2.X` branch and tagged as `v2.X.Y`. diff --git a/docs/release/packages.md b/docs/release/packages.md index 6a6d005e..0f8534c7 100644 --- a/docs/release/packages.md +++ b/docs/release/packages.md @@ -44,9 +44,9 @@ Patch releases should be used when updating dependencies such as `k8s.io/api` fr 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. - -Given that Kubernetes does not follow semver, a Kubernetes package minor version bump may introduce breaking changes. -If a Kubernetes update requires a breaking change in a Flux package public API, then a major version release is necessary. +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