Project: Metal³ (Provisioning / Automation & Configuration)
File: releasing.md

This document details the steps to create a release for `baremetal-operator` aka BMO. NOTE: Always follow . Release documentation in release branches may be outdated. Things you should check before making a release: Check the for high-level process and possible follow-up actions Use the `./hack/verify-release.sh` script as helper to identify possible issues to be addressed before creating any release tags. It verifies issues like: Verify controller Go modules use latest corresponding CAPI modules Verify any other direct or indirect dependency is uplifted to close any public vulnerabilities Creating a release requires repository `write` permissions for: Tag pushing Branch creation GitHub Release publishing These permissions are implicit for the org admins and repository admins. Release team member gets his/her permissions via `metal3-release-team` membership. This GitHub team has the required permissions in each repository required to release BMO. Adding person to the team gives him/her the necessary rights in all relevant repositories in the organization. Individual persons should not be given permissions directly. BMO uses . Regular releases: `v0.x.y` Beta releases: `v0.x.y-beta.z` Release candidate releases: `v0.x.y-rc.z` Clone the repository: `git clone git@github.com:metal3-io/baremetal-operator` or if using existing repository, verify your intended remote is set to `metal3-io`: `git remote -v`. For this document, we assume it is `origin`. If creating a new minor branch, identify the commit you wish to create the branch from, and create a branch `release-0.x`: `git checkout <sha> -b release-0.x` and push it to remote: `git push origin release-0.x` to create it If creating a new patch release, use existing branch `release-0.x`: `git checkout origin/release-0.x` First we create a primary release tag, that triggers release note creation and image building processes. Create a signed, annotated tag with: `git tag -s -a v0.x.y -m v0.x.y` Push the tags to the GitHub repository: `git push origin v0.x.y` This triggers two things: GitHub action workflow for automated release process creates a draft release in GitHub repository with correct content, comparing the pushed tag to previous tag. Running actions are visible on the page, and draft release will be visible on top of the page. GH action `build-images-action` starts building release image with the release tag in Jenkins, and it gets pushed to Quay. Make sure the release tag is visible in . If the release tag build is not visible, check if the action has failed and retrigger as necessary. Also is built and tagged. We also need to create one or more tags for the Go modules ecosystem: For any subdirectory with `go.mod` in it (excluding `hack/tools`), create another Git tag with directory prefix, ie. `git tag apis/v0.x.y`, `git tag test/v0.x.y` and `git tag pkg/hardwareutils/v0.x.y`. This enables the tags to be used as a Gomodule version for any downstream

NOTE: Do not create annotated tags (`-a`, or implicitly via `-m` or `-s`) for Go modules. Release notes expects only the main tag to be annotated, otherwise it might create incorrect release notes. Next step is to clean up the release note manually. Release note has been generated by the `release` action, do not click the `Generate release notes` button. In case there is issue with release action, you may rerun it via `Actions` tab, or you can `make release-notes` to get a markdown file with the release content to be inserted. If release is not a beta or release candidate, check for duplicates, reverts, and incorrect classifications of PRs, and whatever release creation tagged to be manually checked. For any superseded PRs (like same dependency uplifted multiple times, or commit revertions) that provide no value to the release, move them to Superseded section. This way the changes are acknowledged to be part of the release, but not overwhelming the important changes contained by the release. If the release you're making is not a new major release, new minor release, or a new patch release from the latest release branch, uncheck the box for latest release. If it is a release candidate (RC) or a beta release, tick pre-release box. Save the release note as a draft, and have others review it. We need to verify all release artifacts are correctly built or generated by the release workflow. For a release, we should have the following artifacts: We can use `./hack/verify-release.sh` to check for existence of release artifacts, which should include the following: Git tags pushed: Primary release tag: `v0.x.y` Go module tags: `apis/v0.x.y`, `test/v0.x.y` and `pkg/hardwareutils/v0.x.y` Container images built and tagged at Quay registry: Files included in the release page: Source code After everything is checked out, hit the `Publish` button your GitHub draft release! Some post-release actions are needed if new minor or major branch was created. Branch protection rules need to be applied to the new release branch. Copy the settings after the previous release branch, with the exception of `Required tests` selection. Required tests can only be selected after new keywords are implemented in Jenkins JJB, and project-infra, and have been run at least once in the PR targeting the branch in question. Branch protection rules require user to have `admin` permissions in the repository. Update `README.md` with release specific information, both on `main` and in the new `release-0.x` branch as necessary. In the `release-0.x` branch, update the build badges in the `README.md` to point to correct Jenkins jobs, so the build statuses of the release branch are visible. Further additional actions are required in the Metal3 project after BMO release. For that, please continue following the instructions provided in