Merge pull request #1528 from camilamacedo86/add-doc-versions

doc: add versions information to the contribution guidelines

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/).