turtles/docs/release.md

Rancher Turtles Releases

Release Cadence

• New Rancher Turtles versions are usually released every 2-4 weeks.

Release Process

Cutting a release

1. Clone the repository locally:

git clone git@github.com:rancher/turtles.git

2. Depending on whether you are cutting a minor/major, patch, or release candidate, the process varies.

   • If you are cutting a new minor/major release:

     Create a new release branch (i.e release-X) and push it to the upstream repository.

         # Note: `upstream` must be the remote pointing to `github.com/rancher/turtles`.
         git checkout -b release-0.4
         git push -u upstream release-0.4
         # Export the tag of the minor/major release to be cut, e.g.:
         export RELEASE_TAG=v0.4.0
     

   • If you are cutting a patch release from an existing release branch:

     Use existing release branch.

         # Note: `upstream` must be the remote pointing to `github.com/rancher/turtles`
         git checkout upstream/release-0.4
         # Export the tag of the patch release to be cut, e.g.:
         export RELEASE_TAG=v0.4.1
     

   • For release candidates:

     There's no need to create a release branch: use main and follow step 3 to create and push the new tag.

         # Export the tag of the release candidate, e.g.:
         export RELEASE_TAG=v0.4.0-rc.0
     

3. Create a signed/annotated tag and push it:

# Create tags locally
git tag -s -a ${RELEASE_TAG} -m ${RELEASE_TAG}
git tag -s  -a test/${RELEASE_TAG} -m "Testing framework ${RELEASE_TAG}"
git tag -s  -a examples/${RELEASE_TAG} -m "ClusterClass examples ${RELEASE_TAG}"

# Push tags
git push upstream ${RELEASE_TAG}
git push upstream test/${RELEASE_TAG}
git push upstream examples/${RELEASE_TAG}

This will trigger a release GitHub action that creates a release with Rancher Turtles components.

Note: If you are cutting a new minor/major release, please follow the next step below, otherwise skip.

Announcing a release

When the new release is available, we need to notify a list of Slack channels so users and relevant stakeholders can stay up to date with the latest version and changes:

• SUSE Software Solutions discuss-rancher-cluster-api
• Rancher Users cluster-api

You can use the following notification template and adapt it to the specifics of the release you are announcing:

Hi all! We are happy to announce a new release of Rancher Turtles - vx.x.x! With this release we <one line summary of the release>:
- list of relevant features/fixes
- ...
Please, take a look at the release notes <here link to GitHub release notes>.

Mandatory Post-release steps

If a new minor/major branch was created, there are some post-release actions that need to be taken. If you cut a patch release before, please disregard publish a new Turtles Community Documentation version and create a JIRA ticket for Documentation syncing steps below.

Write release description for non-developers

Turtles release notes are automatically generated based on the commits that are published with the new version.

These commit messages are usually hard to understand for those that are not very familiar with the project and we must add a "human-readable" description of what the release brings at the beginning of release notes. This can be used for reference.

Rancher Turtles Community Documentation

Update component versions in documentation

Before publishing a new version of the documentation, component versions used in the documentation must be updated.

1. Navigate to the Rancher Turtles Docs repository: rancher/turtles-docs
2. Go to Actions and start a new run of Update Component Versions.
3. Look up the correct component versions from the rancher/turtles repository and fill them into the input fields. If any input fields are left blank, the workflow will retain the currently documented versions for those components.
4. This will generate a new PR in the same repository that updates the documentation with the specified versions.

Generate changelog from Turtles release notes

Before publishing a new version of the documentation, a new Changelog must be generated to include the new release.

1. Navigate to the Rancher Turtles Docs repository: rancher/turtles-docs
2. Go to Actions and start a new run of Updatecli.
3. This will generate a new PR in the same repository that adds the release notes from any new Turtles release.

Publish Rancher Turtles Docs

1. Clone the Rancher Turtles Docs repository locally:

git clone git@github.com:rancher/turtles-docs.git

2. Export the tag of the minor/major release, create a signed/annotated tag and push it:

# Export the tag of the minor/major release in a format of v0.Y.Z/v1.Y.Z, e.g.:
export RELEASE_TAG=v0.4.0

# Create tags locally
git tag -s -a ${RELEASE_TAG} -m ${RELEASE_TAG}

# Push tags
# Note: `upstream` must be the remote pointing to `github.com/rancher/turtles-docs`
git push upstream ${RELEASE_TAG}

3. Wait for the version publish workflow to create a pull request. The PR format is similar to reference. Merging it would result in automatic documentation being published using the publish workflow.

The resulting state after the version publish workflow for the released tag is also stored under the release-${RELEASE_TAG} branch in the origin repository, which is consistent with the branching strategy for turtles.

Once all steps above are completed, a new version of Rancher Turtles Community Docs should be available at [https://turtles.docs.rancher.com].

Create a JIRA ticket for syncing Turtles Community Docs with Product Docs

Follow the steps below to create a JIRA ticket:

• navigate to JIRA.
• take a look at reference issue and create a similar ticket for syncing the new Turtles Community Docs version that was published in previous step with Turtles Product Docs. In the ticket description, make sure to include the reference to latest published version of Rancher Turtles Community Docs and PR created automatically by GitHub Actions bot.

Versioning

Rancher Turtles follows semantic versioning specification.

Example versions:

• Pre-release: v0.4.0-alpha.1
• Minor release: v0.4.0
• Patch release: v0.4.1
• Major release: v1.0.0

With the v0 release of our codebase, we provide the following guarantees:

• A (minor) release CAN include:

  • Introduction of new API versions, or new Kinds.
  • Compatible API changes like field additions, deprecation notices, etc.
  • Breaking API changes for deprecated APIs, fields, or code.
  • Features, promotion or removal of feature gates.
  • And more!

• A (patch) release SHOULD only include backwards compatible set of bugfixes.

Backporting

Any backport MUST not be breaking for either API or behavioral changes.

It is generally not accepted to submit pull requests directly against release branches (release-X). However, backports of fixes or changes that have already been merged into the main branch may be accepted to all supported branches:

• Critical bugs fixes, security issue fixes, or fixes for bugs without easy workarounds.
• Dependency bumps for CVE (usually limited to CVE resolution; backports of non-CVE related version bumps are considered exceptions to be evaluated case by case)
• Cert-manager version bumps (to avoid having releases with cert-manager versions that are out of support, when possible)
• Changes required to support new Kubernetes versions, when possible. See supported Kubernetes versions for more details.
• Changes to use the latest Go patch version to build controller images.
• Improvements to existing docs (the latest supported branch hosts the current version of the book)

Note: We generally do not accept backports to Rancher Turtles release branches that are out of support.

Branches

Rancher Turtles has two types of branches: the main and release-X branches.

The main branch is where development happens. All the latest and greatest code, including breaking changes, happens on main.

The release-X branches contain stable, backwards compatible code. On every major or minor release, a new branch is created. It is from these branches that minor and patch releases are tagged. In some cases, it may be necessary to open PRs for bugfixes directly against stable branches, but this should generally not be the case.

Support and guarantees

Rancher Turtles maintains the most recent release/releases for all supported APIs. Support for this section refers to the ability to backport and release patch versions; backport policy is defined above.

• The API version is determined from the GroupVersion defined in the top-level api/ package.
• For the current stable API version (v1alpha1) we support the two most recent minor releases; older minor releases are immediately unsupported when a new major/minor release is available.