From 80a60ee45b3f4912cb6ea5f47a700a3873ba5510 Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Fri, 29 May 2020 12:29:17 +0100 Subject: [PATCH] doc: add versions info --- CONTRIBUTING.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a08dfb601d..fbba9f817c8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,6 +81,40 @@ cherry-picked into `book-v2` branch. Check the CI job after to do the Pull Request and then, click on in the `Details` of `netlify/kubebuilder/deploy-preview` +## Understanding the versions + +| Name | Example | Description | +|--- |--- |--- | +| 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. | +| 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. | +| Plugin Versions | `go.kubebuilder.io/v2.0.0` | Represents the version of an individual plugin, as well as the corresponding scaffolding that it generates. | + +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. + +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. + +For more information on how the release and plugin versions work, see the the [semver](https://semver.org/) documentation. + +**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. + +## Introducing changes in the scaffold files + +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. + +**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. + +**EXAMPLE:** + +KubeBuilder Release version (`5.3.1`) scaffolds projects with the plugin version `3.2.1` by default. + +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. + +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`. + +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. + +**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`. + ## Community, discussion and support Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).