This document defines how releases of the kubestellar/kubestellar repository are made, including the corresponding documentation updates in the separate kubestellar/docs repository. This document is a work-in-progress.
This document starts with step-by-step instructions for the current procedure, then proceeds with the thinking behind them.
See the associated packaging and delivery doc for some clues about the problem.
Every release should pass all release tests before it can be officially declare as a new stable release. Please see the details in release-testing.
go.modgo mod tidycore-chart/Chart.yaml.github/workflows that work with the main branch of ks/ks:
.github/workflows/ocp-self-runner.yml.github/workflows/pr-test-e2e.yml.github/workflows/pr-test-integration.yml.github/workflows that work with the latest release of ks/ks
.github/workflows/test-latest-release.ymlOr you could search for appearances of the old release string yourself using a command like the following. And maybe also search for the release before that, in case it was overlooked earlier.
find * .github/workflows \( -name "*.svg" -prune \) -or \( -path "*venv" -prune \) -or \( -path hack/tools -prune \) -or \( -type f -exec fgrep 0.6.2 \{\} \; -print -exec echo \; \)docs/content/kubestellar/pre-reqs.mdscripts/check_pre_req.shBetween each release of ks/OSA and the next release of ks/ks, update the references to the ocm-status-addon release in the following files.
core-chart/values.yamlmonitoring/README.mdMaking a new kubestellar release requires a contributor to do the following things. Here $version is the semver identifier for the release (e.g., 1.2.3-rc2).
If not already in effect, declare a code freeze. There should be nothing but bug fixes and doc improvements while working towards a regular release.
Update the version in scripts/check_pre_req.sh.
Update the version in the core chart defaults, core-chart/values.yaml.
Update the version in scripts/create-kubestellar-demo-env.sh. Note: merging this change will cause the script to be broken until the release is made.
—shot changes for upgrade to Kubernetes 1.32. Remove this list after these changes are made.
Update .github/workflows/test-latest-release.yml: KubeFlex to 0.9.3, clusteradm 1.0.0 (both places)
Update .github/workflows/test-demo-env-creation-script.yml: clusteradm to 1.0.0
Update test/scale-infra/deploy_ks_core.yaml: KubeFlex to 0.9.3, clusteradm to 1.0.0
Update test/scale-infra/deploy_ks_wec.yaml: clusteradm to 1.0.0
Update config/default/manager_auth_proxy_patch.yaml: kube-rbac-proxy to v0.20.2
Update test/performance/short-running-tests/README.md: github.com/kubernetes/perf-tests to release-1.32
Update test/performance/long-running-tests/README.md: github.com/kubernetes/perf-tests to release-1.32
Update scripts/create-kubestellar-demo-env.sh: update the prefetched images
Make a new Git commit with those ks/ks changes and get it into the right branch in kubestellar/kubestellar (through the regular PR process if not authorized to cheat).
Wait for successful completion of the testing after that merge.
Apply the Git tag v$version to that new commit in kubestellar/kubestellar.
After that, the “goreleaser” GitHub workflow then creates and publishes the artifacts for that release (as discussed above) and then the “Test latest release” workflow will run the E2E tests using those artifacts.
Verify that the automatic tests indeed executed and passed (see more details in CICD release testing)
After the release artifacts have been published, create and push to kubestellar/kubestellar a branch named release-$version. This will also trigger the workflow that tests the latest release. Every push to a branch with such a name triggers that workflow, in case there has been a change in an E2E test for that release.
Follow the procedure in OCP testing, to verify that the release is functional on OCP.
If the test results are good and the release is regular (not an RC) then declare the code freeze over.
kubestellar/docs repository.Edit docs/mkdocs.yml and update the definition of ks_latest_release to $version (e.g., '0.23.0-rc42'). If this is a regular release then also update the definition of ks_latest_regular_release.
Edit the release notes in docs/content/kubestellar/release-notes.md.
When publishing the versioned KubeStellar docs for that release from kubestellar/docs, create or update the branch docs/$version after the relevant docs changes are merged.
The release process has the following goals.
kubestellar/kubestellar tagged with a tag whose name is “v” followed by the release identifier.main always work. This includes passing CI tests in ks/ks and documentation being accurate in ks/docs. We allow point-in-time specific documentation, such as a document that says “Here is how to use release 1.2.3” --- which would refer to a release made in the past. We do not require the documentation in main to document all releases.1.2.3 does not require changing any file in Git to have the string 1.2.3 in it.We have the following limitations.
values.yaml file. Another is in the Getting Started setup instructions.There is a GitHub workflow that creates the published artifacts for each Git tag whose name starts with “v”. The rest of the tag name is required to be a semver release identifier. Note that this document does not (yet, anyway) specify how that GitHub workflow gets its job done. This workflow is confusingly named “goreleaser” and in a file named “goreleaser.yml” and has a job named “goreleaser” despite the fact that it does more than use goreleaser.
For each tag v$version the following published artifacts will be created.
ghcr.io/kubestellar/kubestellar/controller-manager. Image tag will be $version. This GitHub “package” will be connected to the ks/ks repo (this connection is something that an admin will do, it will stick for all versions).ghcr.io/kubestellar/kubestellar/ocm-transport-controller. Image tag will be $version. This GitHub “package” will be connected to the ks/ks repo (this connection is something that an admin will do, it will stick for all versions).ghcr.io/kubestellar/kubestellar/core-chart with version $version and Helm “appVersion” $version. This GitHub “package” will also be connected to the ks/ks repo. The chart has a reference to container image for the KCM and that reference is ghcr.io/kubestellar/kubestellar/controller-manager:$version. The chart also has a reference to container image for the OTC and that reference is ghcr.io/kubestellar/kubestellar/ocm-transport-controller:$version. In Git the chart has placeholders in these places, not $version; the $version is inserted into a distinct copy by the GitHub workflow, which then publishes this specialized copy.We use mike and MkDocs to derive and publish GitHub pages. For information about contributing documentation, see Contributing to Docs/Website.
The published GitHub pages are organized into versions. In kubestellar/docs, the development docs live on main and the versioned KubeStellar docs live on branches named docs/$version.
Our documentation is, mostly, viewable in either of two ways. The source documents can be viewed directly through GitHub’s web UI for files. The other way is through the website.
The unit tests (of which we have almost none right now), integration tests (of which we also have very few), and end-to-end (E2E) tests in the kubestellar/kubestellar repository are run in the context of a local copy of that repository and test that version of ks/ks --- not using any published release artifacts. Additionally, some E2E tests have the option to test published artifacts instead of the local copy of ks/ks.
The end-to-end tests include written in bash, and these provide executable examples for the current version of kubestellar/kubestellar. Again, these tests do not use any published artifacts from a release of ks/ks.
We have another category of tests, release tests. These test a given release, using the published artifacts of that release. These differ from the non-release tests in the setup script, where it uses the published core Helm chart instead of the local version and uses published image tags rather than ephemeral local.
We have GitHub workflows that exercise the E2E tests, normally on the copy of the repo that the workflow applies to. However, these workflows are parameterized and can be told to test the released artifacts instead.
We also have a GitHub workflow, named “Test latest release” in .github/workflows/test-latest-release.yml, that invokes those E2E tests on the latest release. This workflow can be triggered manually, and is also configured to run after completion of the workflow (“goreleaser”) that publishes release artifacts.
We will maintain a document that lists releases that pass our quality bar. The latest of those is thus the latest stable release. This document is updated on the main branch of kubestellar/docs as quality evaluations come in.
We used to maintain a statement of what is the latest stable release in docs/content/kubestellar/README.md.
We maintain a Getting Started document that tells users how to exercise the release that the document appears in. This requires a self-reference that is updated as part of the release process.
We aim for all regular releases to be working. In order to do that, we have to make test releases and test them. The widely recognized pattern for doing that is to make “release candidates” (i.e., releases for testing purposes) 1.2.3-rc0, 1.2.3-rc1, 1.2.3-rc2, and so on, while trying to get to a quality release 1.2.3. of them is judged to be of passing quality, we make a release without the -rc<N> suffix. Due to the self-references in the repo, this will involve making a new commit.
Right after making a release we test it thoroughly.
We plan a few deliberately feature-incomplete releases. They will be regular releases as far as the technology here is concerned. They will be announced to selected users who acknowledge that they are getting something that is incomplete. In GitHub, these will be marked as “pre-releases”. The status of these releases will be made clear in their documentation (which currently appears in the release notes.
We aim to keep the documents viewable both through the website and GitHub’s web UI for viewing files. We aim for all of the documentation to be reachable on the website and in the GitHub file UI starting from the repository’s README.md.
We create a versioned GitHub pages publication for every release. A patch release is a release. A test release is a release. In kubestellar/docs, creating that KubeStellar docs publication is done by creating or updating a git branch named docs/$version.
Some KubeStellar-related component repositories (for example,
kubectl-multi-plugin) automatically trigger documentation updates
when a new release is published.
When such a release is created:
This automation ensures that published documentation stays aligned with released components and reduces the need for manual documentation updates during the release process.
We intend to get rid of the self-reference in the KCM PCH, as follows. Define a Helm chart for installing the PCH. Update the release workflow to specialize that Helm chart, similarly to the specialization done for the KCM Helm chart.
Exactly when does a new release branch diverge from main? What about cherry-picking between main and the latest (or also earlier?) release branch?
What about the clusteradm container image?