Skip to content

Latest commit

 

History

History
176 lines (129 loc) · 7.45 KB

releasing.md

File metadata and controls

176 lines (129 loc) · 7.45 KB

cluster-api-provider-metal3 releasing

This document details the steps to create a release for cluster-api-provider-metal3 aka CAPM3.

NOTE: Always follow release documentation from the main branch. Release documentation in release branches may be outdated.

Before making a release

Things you should check before making a release:

  • Check the Metal3 release process for high-level process and possible follow-up actions
  • Verify CAPI go module is uplifted in root, api/ and test/ go modules and cluster-api/test module in test/ go module. Prior art: #1157
  • Verify controller Go modules use latest corresponding CAPI modules. Prior art: #1145
  • Verify BMO's apis and pkg/hardwareutils dependencies are the latest. Prior art: #1163
  • Uplift IPAM api dependency, container image version , and manifest resource . Prior art: #999
  • Verify any other direct or indirect dependency is uplifted to close any public vulnerabilities

Use the ./hack/verify-release.sh script as helper to identify possible issues to be addressed before creating any release tags.

Permissions

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

Process

CAPM3 uses semantic versioning. For version v1.x.y:

Repository setup

Clone the repository: git clone [email protected]:metal3-io/cluster-api-provider-metal3

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-1.x: git checkout <sha> -b release-1.x and push it to remote: git push origin release-1.x to create it
  • If creating a new patch release, use existing branch release-1.x: git checkout origin/release-1.x

Tags

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 v1.x.y -m v1.x.y
  • Push the tags to the GitHub repository: git push origin v1.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 Actions page, and draft release will be visible on top of the Releases page.
  • Quay starts building release image with the release tag. Make sure the release is built successfully in Quay builds page. If the release tag build is not visible, check if the build trigger is enabled. Quay disables build trigger sometimes when build has failed few times.

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 api/v1.x.y and git tag test/v1.x.y. This enables the tags to be used as a Go module version for any downstream users.

    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. Push both of the tags to origin.

Release artifacts

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:

Git tags pushed:

  • Primary release tag: v1.x.y
  • Go module tags: api/v1.x.y, test/v1.x.y

Container images built and tagged at Quay registry:

Files included in the release page:

  • A manifest file - infrastructure-components.yaml
  • A metadata file - metadata.yaml
  • A cluster template - cluster-template.yaml
  • A file containing an example of variables to set - example_variables.rc

Release notes

Next step is to clean up the release note manually.

  • 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 pre-release, tick pre-release box.
  • Save the release note as a draft, and have others review it. Use the ./hack/verify-release.sh script as helper to verify release content.
  • Publish the release.

Post-release actions for new release branches

Some post-release actions are needed if new minor or major branch was created.

Branch protection rules

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 in project-infra, and have been run at least once in the PR targeting the branch in question.

NOTE: Branch protection rules need repository admin rights to modify.

Update README.md and build badges

Update README.md with release specific information, both on main and in the new release-1.x branch as necessary.

Example

In the release-1.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.

Example

Additional actions outside this repository

Further additional actions are required in the Metal3 project after CAPM3 release. For that, please continue following the instructions provided in Metal3 release process