|
| 1 | +# Versioning and Releasing for KubeBuilder |
| 2 | + |
| 3 | +We (mostly) follow the [common KubeBuilder versioning |
| 4 | +guidelines][guidelines], and use the corresponding tooling and PR process |
| 5 | +described there. |
| 6 | + |
| 7 | +For the purposes of the aforementioned guidelines, KubeBuilder counts as |
| 8 | +a "CLI project". |
| 9 | + |
| 10 | +[guidelines]: https://sigs.k8s.io/kubebuilder-release-tools/VERSIONING.md |
| 11 | + |
| 12 | +## Compability |
| 13 | + |
| 14 | +Note that we generally do not support older release branches, except in |
| 15 | +extreme circumstances. |
| 16 | + |
| 17 | +Bear in mind that changes to scaffolding generally constitute breaking |
| 18 | +changes -- see [below](#understanding-the-versions) for more details. |
| 19 | + |
| 20 | +## Releasing |
| 21 | + |
| 22 | +When releasing, you'll need to: |
| 23 | + |
| 24 | +- to update references in [the build directory](build/) to the latest |
| 25 | + version of the [envtest tools](#tools-releases) **before tagging the |
| 26 | + release.** |
| 27 | + |
| 28 | +- reset the book branch: see [below](#book-releases) |
| 29 | + |
| 30 | +You may also want to check that the book is generating the marker docs off |
| 31 | +the latest controller-tools release. That info is stored in |
| 32 | +[docs/book/install-and-build.sh](/docs/book/install-and-build.sh). |
| 33 | + |
| 34 | +## Book Releases |
| 35 | + |
| 36 | +The book's main version (https://book.kubebuilder.io) is published off of |
| 37 | +the [book-v2][book-branch] (a version built off the main branch can be |
| 38 | +found at https://master.book.kubebuilder.io). |
| 39 | + |
| 40 | +Docs changes that aren't specific to a new feature should be |
| 41 | +cherry-picked to the aforementioned branch to get them to be published. |
| 42 | +The cherry-picks will automatically be published to the book once their PR |
| 43 | +merges. |
| 44 | + |
| 45 | +**When you publish a KubeBuilder release**, be sure to also submit a PR |
| 46 | +that merges the main branch into [book-v2][book-branch], so that it |
| 47 | +describes the latest changes in the new release. |
| 48 | + |
| 49 | +[book-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases |
| 50 | + |
| 51 | +## Tools Releases |
| 52 | + |
| 53 | +In order to update the [envtest tools][envtest-ref], you'll need to do an |
| 54 | +update to the [tools-releases branch][tools-branch]. Simply submit a PR |
| 55 | +against that branch that changes all references to the current version to |
| 56 | +the desired next version. Once the PR is merged, Google Cloud Build will |
| 57 | +take care of building and publishing the artifacts. |
| 58 | + |
| 59 | +[envtest-ref]: https://book.kubebuilder.io/reference/artifacts.html |
| 60 | +[tools-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases) |
| 61 | + |
| 62 | +## Understanding the versions |
| 63 | + |
| 64 | +| Name | Example | Description | |
| 65 | +|--- |--- |--- | |
| 66 | +| PROJECT version | `v1`,`v2`,`v3` | As of the introduction of [Extensible CLI and Scaffolding Plugins](https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md), PROJECT version represents the layout of PROJECT file itself. For `v1` and `v2` projects, there's extra meaning -- see below. | |
| 67 | +| Release version | `v2.2.0`, `v2.3.0`, `v2.3.1` | Tagged versions of the KubeBuilder project, representing changes to the source code in this repository. See the [releases](https://github.com/kubernetes-sigs/kubebuilder/releases) page. | |
| 68 | +| Plugin Versions | `go.kubebuilder.io/v2.0.0` | Represents the version of an individual plugin, as well as the corresponding scaffolding that it generates. | |
| 69 | + |
| 70 | +Note that PROJECT version should only be bumped if a breaking change is introduced in the PROJECT file format itself. Changes to the Go scaffolding or the KubeBuilder CLI *do not* affect the PROJECT version. |
| 71 | + |
| 72 | +Similarly, the introduction of a new major version (`(x+1).0.0`) of the Go plugin might only lead to a new minor (`x.(y+1).0`) release of KubeBuilder, since no breaking change is being made to the CLI itself. It'd only be a breaking change to KubeBuilder if we remove support for an older version of the plugin. |
| 73 | + |
| 74 | +For more information on how the release and plugin versions work, see the the [semver](https://semver.org/) documentation. |
| 75 | + |
| 76 | +**NOTE:** In the case of the `v1` and `v2` PROJECT version, a corresponding Plugin version is implied and constant -- `v1` implies the `go.kubebuilder.io/v1` Plugin, and similarly for `v2`. This is for legacy purposes -- no such implication is made with the `v3` PROJECT version. |
| 77 | + |
| 78 | +## Introducing changes in the scaffold files |
| 79 | + |
| 80 | +Changes in the scaffolded files require a new Plugin version. If we delete or update a file that is scaffolded by default, it's a breaking change and requires a `MAJOR` Plugin version. If we add a new file, it may not be a breaking change. |
| 81 | + |
| 82 | +**More simply:** any change that will break the expected behaviour of a project built with the previous `MINOR` Plugin versions is a breaking change to that plugin. |
| 83 | + |
| 84 | +**EXAMPLE:** |
| 85 | + |
| 86 | +KubeBuilder Release version (`5.3.1`) scaffolds projects with the plugin version `3.2.1` by default. |
| 87 | + |
| 88 | +The changes introduced in our PR will not work well with the projects which were built with the plugin versions `3.0.0...3.5.1` without users taking manual steps to update their projects. Thus, our changes introduce a breaking change to the Go plugin, and require a `MAJOR` Plugin version bump. |
| 89 | + |
| 90 | +In the PR, we should add a migration guide to the [Migrations](https://book.kubebuilder.io/migrations.html) section of the KubeBuilder book. It should detail the required steps that users should take to upgrade their projects from `go.kubebuilder.io/3.X.X` to the new `MAJOR` Plugin version `go.kubebuilder.io/4.0.0`. |
| 91 | + |
| 92 | +This also means we should introduce a new KubeBuilder minor version `5.4.0` when the project is released: since we've only added a new plugin version without removing the old one, this is considered a new feature to KubeBuilder, and not a breaking change. |
| 93 | + |
| 94 | +**IMPORTANT** Breaking changes cannot be made to PROJECT versions v1 and v2, and consequently plugin versions `go.kubebuilder.io/1` and `go.kubebuilder.io/2`. |
| 95 | + |
0 commit comments