Release Process

This document explains the process of a KubeArchive release and its requirements.

Commits

The KubeArchive release process scans commits from the latest tag up to the current commit. The commits must mention the GitHub Pull Requests they come from on their title (first line). A commit merged from the Pull Request with ID 100 should have this title:

Add feature A (#100)

The Pull Request mention is added by default when the commits are squashed on Pull Request merge.

Pull Request Labels

KubeArchive follows the Semantic Versioning system with a leading v: vMAJOR.MINOR.PATCH. To summarize, MAJOR releases break user-facing interfaces, MINOR releases introduce new features and PATCH versions introduce bug fixes or documentation changes.

The KubeArchive release process relies on the labels on the GitHub Pull Requests when determining the next version number for the release. The following labels impact which number is updated in the next release:

  • kind/breaking: next release is a MAJOR version. MINOR and PATCH numbers are reset to 0.

  • kind/feature: if kind/breaking is not present, next release is a MINOR version. PATCH number is reset to 0.

  • kind/documentation and kind/bug: if kind/breaking and kind/feature are not present, next release is a PATCH version.

A Pull Request requires at least one of these labels.

Release Notes

The KubeArchive release process creates release notes for users. Changes that have user-visible impact are required to provide release notes.

Some examples of changes that would require release notes are:

  • Optimized the code increasing the overall speed by a signifcant amount.

  • Fixed bug where some configuration option was ignored.

  • Introduced a new configuration option.

  • Rewrote a whole documentation page that is relevant to users.

  • Added a documentation page covering a topic relevant to users.

Some examples of changes that would not require release notes are:

  • Fixed typos on a documentation page.

  • Improvements on contributor relevant topics such as test coverage, maintainability, naming conventions…​

  • Reduced time to perform integration testing.

  • Added missing tests.

The notes are generated from the GitHub Pull Requests that contain a code block annotated with release-note. An example of a release-note code block:

```release-note
Introduced new feature called `feature-a`. To enable it, set to `true` the
`feature-a` flag in the `feature-flags` ConfigMap in the `kubearchive` namespace.
```

To not include release notes from the Pull Request the release-note block must contain the string NONE:

```release-note
NONE
```

This code block is included in KubeArchive’s Pull Request template.

Writing Release Notes

The Release Notes should comply with the following rules:

  • They should be clear for users that install and operate KubeArchive but that did not look at the source code.

  • They are capitalized and start with a verb in the present tense. Often the verb will be "Adds", "Fixes", "Changes".

  • They should not mention specific internal implementation details. For example do not mention method names. They can mention KubeArchive’s components: Sink, API and Operator. They can mention external specific details, for example a configuration key.

Examples of Release Notes

  • Adds [pprof](https://pkg.go.dev/net/http/pprof) endpoints enabled by default.

  • Changes the default log returned from the first container to the one specified in the annotation kubectl.kubernetes.io/default-container.

  • Adds optional [labelSelector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) query parameter in most of the API endpoints.

  • Adds documentation about how to support a new database.

  • Adds retries when resource updates are not processed correctly.

  • Fixes a bug where resource updates were always rejected, causing performance problems.

  • Improves API speed when requesting resources cluster-wide.

Examples of Bad Release notes

  • Adds [pprof](https://pkg.go.dev/net/http/pprof) endpoints enabled by default controlled by the environment variable KUBEARCHIVE_ENABLE_PPROF. Endpoints are on different ports for each KubeArchive’s Component (KubeArchive Operator 8082, KubeArchive Sink 80, KubeArchive API 8081). The endpoint is /debug/pprof/ for all of them. Use it with curl or directly with go tool pprof -http :8083 http://localhost:8080/debug/pprof/heap. Implementation is in pkg/observability/pprof.go.

    • This release note is useful but questionably long, it gives too much detail which means that it probably needs a dedicated documentation page, it also mentions too many technical details.

  • KubeArchive had a bug where resource updates were always rejected, causing performance problems. This was in the method receiveCloudEvent on the Sink. It was wrong because it was returning an HTTP code that was not aligned with CloudEvents implementation.

    • This release note mentions method names and has superfluous wording as "KubeArchive had a bug" instead of directly "Fixes a bug", "It was wrong because it was returning…​" instead of "The Sink returned a wrong HTTP Code".

Steps

  1. Merge the changes needed into main.

  2. Make sure the latest commit in main has passed every test.

  3. Go to the Actions tab on the KubeArchive repository.

  4. Trigger the "Release" workflow.

Release Results

  1. A release commit is created adding the VERSION files.

  2. A release tag is created from the release commit.

  3. A GitHub release is created from the release tag.

  4. Images are pushed with the <version> tag to https://quay.io/kubearchive.

Testing

The release workflow is prepared to be run within forks. You can run it locally or on your fork Actions.

Testing Locally

Read the top of the script and install the tools listed there. Export the "externally provided variables" listed on the script with proper values. These variables provide authentication for some of the tools, login manually with the rest of the tools. Then run the script:

bash hack/release.sh

To cleanup the results of the release, complete the following steps:

  • Delete the images created on the OCI repository.

  • Delete the release and the tag using the GitHub UI.

  • Delete the new tag in your local repository.

  • Execute the following commands from your repository:

    git reset --hard HEAD~1  # go back to previous commit
git push --force  # rewrite fork history to delete the release commit

Testing from Fork

Add the following secrets to your fork:

  • OCI_USERNAME

  • OCI_PASSWORD

Add the following variables to your fork:

  • OCI_REGISTRY: used to login with Ko (for example "quay.io").

  • OCI_REPOSITORY: used to push images (for example "quay.io/username")

Then execute the release workflow from the branch you are making changes to.

To cleanup the results of the release, complete the following steps.

  • Delete the different artifacts created on the OCI repository.

  • Delete the release and the tag using the GitHub UI.

  • From your local git repository run git push --force to delete the commit introduced by the workflow on the remote repository.

Notes

  1. The release process uses the Kubernetes tool release-notes. Using this tool delegates complexity but makes us follow certain practices such as using kind/* labels on GitHub Pull Requests.