doc: add versions info

CONTRIBUTING.md

@@ -81,6 +81,50 @@ 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.
+
+<aside class="note">
+<h4>**NOTE:**</h4>
+
+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.
+
+</aside>
+         
+## 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. 
+
+<aside class="note">
+<h4>**Example:**</h4>
+
+The current latest 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 be 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.
+
+</aside>
+
+**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/).