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

Document various release procedures

Browse Source 
This lacks documentation for the Terraform provider repository, which
is a higher level component than anything documented here.

Signed-off-by: Hidde Beydals <hidde@hhh.computer>
pull/3254/head
Hidde Beydals 2 years ago committed by Stefan Prodan
parent 33be9840f0
commit 4e78e80619
No known key found for this signature in database
GPG Key ID: 3299AEB0E4085BAF
2 changed files with 432 additions and 47 deletions
Show Stats Download Patch File Download Diff File

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

@ -1,60 +1,373 @@
# Flux release procedure
# Flux release procedures
## Shared packages release procedure
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.
As a project maintainer, to release a package, tag the `main` branch using semver,
and push the signed tag to upstream:
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](#controller-minor-releases)
* [Patch releases](#controller-patch-releases)
* [Release candidates](#controller-release-candidates)
* [Preview releases](#controller-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)
## 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 "runtime/v1.0.0" "runtime/v1.0.0"
git push origin "runtime/v1.0.0"
git tag -s -m "<module>/<semver>" "<module>/<semver>"
git push origin "<module>/<semver>"
```
**Note** that the Git tags must be cryptographically signed with your private key
and your public key must be uploaded to GitHub.
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.
Release candidates of a specific package can be cut from the `main` branch or from an `dev-<pkg-name>` branch:
Here's an example of releasing a candidate from a feature branch:
```shell
git switch dev-runtime
git tag -s -m "runtime/v1.1.0-RC.1" "runtime/v1.1.0-RC.1"
git push origin "runtime/v1.1.0-RC.1"
git switch <feature-branch>
git tag -s -m "<module>/<semver>-<feature>.1" "<module>/<semver>-<feature>.1"
git push origin "<module>/<semver>-<feature>.1"
```
Before cutting a release candidate, make sure the tests are passing on the `dev` branch.
## Controllers release procedure
As a project maintainer, to release a controller and its API:
1. Checkout the `main` branch and pull changes from remote.
2. Create a new branch from `main` i.e. `release-<next semver>`. This
will function as your release preparation branch.
3. Update the `github.com/fluxcd/<NAME>-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.
5. Create a PR for your release branch and get it merged into `main`.
6. Create a `api/<next semver>` tag for the merge commit in `main` and push it to remote.
7. Create a `<next semver>` 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
and your public key must be uploaded to GitHub.
## Distribution release procedure
As a project maintainer, to release a new Flux version and its CLI:
- `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`.
### 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.
##### Controller 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`.
##### Controller 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
```
#### Controller 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](#controller-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](#controller-patch-releases).
#### Controller 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 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/v1.2.x`, and push it to the remote repository.
```shell
git switch -c release/v1.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 "v1.2.0" v1.2.0
git push origin v1.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/v1.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.,
`v1.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 "v1.2.1" v1.2.1
git push origin v1.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., `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](#controller-patch-releases).
#### Distribution release notes
The release notes template for Flux distributions is available in the
[release-notes-template.md](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
```

72
docs/release/release-notes-template.md
Unescape Escape View File

@ -0,0 +1,72 @@
# Release notes template
This is a template for release notes. It is intended to be used as a
starting point for writing release notes for a new release. It should be copied
to a temporary file, and then edited to reflect the changes in the release.
Once the release notes are complete, you can tag the release and push it to
GitHub.
After the release is tagged, the CI will build the release artifacts and upload
them to the GitHub release page. The release notes can then be copied from the
temporary file to the GitHub release page.
The release notes should be formatted using [Markdown](https://guides.github.com/features/mastering-markdown/),
and not make use of line breaks unless they function as paragraph breaks.
For examples of release notes, including language and formatting of the release
highlights, see the [Flux release notes](https://github.com/fluxcd/flux2/releases).
## GitHub release template
The following template can be used for the GitHub release page:
```markdown
## Highlights
<!-- Text describing the most important changes in this release -->
### Fixes and improvements
<!-- List of fixes and improvements to the controllers and CLI -->
## New documentation
<!-- List of new documentation pages, if applicable -->
## Components changelog
- <name>-controller [v<version>](https://github.com/fluxcd/<name>-controller/blob/<version>/CHANGELOG.md
## CLI changelog
<!-- auto-generated list of pull requests to the CLI starts here -->
```
In some scenarios, you may want to include specific information about API
changes and/or upgrade procedures. Consult [the formatting of
`v2.0.0-rc.1`](https://github.com/fluxcd/flux2/releases/tag/v2.0.0-rc.1) for
such an example.
## Slack message template
The following template can be used for the Slack release message:
```markdown
:sparkles: *We are pleased to announce the release of Flux [<version>](https://github.com/fluxcd/flux2/releases/tag/<version>/)!*
<!-- Brief description of most important changes to this release -->
:hammer_and_pick: *Fixes and improvements*
<!-- List of fixes and improvements as in the GitHub release template -->
:books: Documentation
<!-- List of new documentation pages, if applicable -->
:heart: Big thanks to all the Flux contributors that helped us with this release!
```
For more concrete examples, see the pinned messages in the [Flux Slack
channel](https://cloud-native.slack.com/archives/CLAJ40HV3).
Write Preview
Loading…
Cancel
Save