Skip to content

Commit

Permalink
doc: add versions information to the contribution guidelines
Browse files Browse the repository at this point in the history
  • Loading branch information
Camila Macedo committed May 27, 2020
1 parent f07a014 commit 8bce380
Showing 1 changed file with 24 additions and 0 deletions.
24 changes: 24 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,30 @@ 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` | After the Kubebuilder v3 introduces the plugins architecture to [Extensible CLI and Scaffolding Plugins](https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md), the PROJECT version represents the version of the PROJECT file layout which are generated in the projects built with it. |
| Releases version | `v2.2.0`, `v2.3.0`, `v2.3.1` | Represents the release tags of this project. See the [releases](https://github.com/kubernetes-sigs/kubebuilder/releases) page. |
| Plugin Versions | `go.kubebuilder.io/v2.0.0` | Represents the code source of the Plugin used to scaffold the projects. |

Note that, we just need to bump a new PROJECT version if a breaking or significant change be introduce in the PROJECT file. Otherwise, it not requires be changed. And then, see that Releases and Plugin versions following the [semver](https://semver.org/) definition.

## Introducing changes in the scaffold files

Changes in the scaffold files require a new Plugin version. Note that, if we delete and/or update a file or a content that is scaffolded by default, it will result in a breaking change and requires a `MAJOR` Plugin version. But, if we are adding a new content and/or file it probably will not be and breaking change.

For our sake let's try to simplify it and consider that any change that will break the expected behaviour of a project built with the previous `MINOR` Plugin versions will be a breaking change.

**Example**

The master version has been scaffold projects with the plugin version `2.5.1` by default then, if the changes introduced in our PR will not work well with the projects which were built with the plugin versions >= `2.0.0` <= `2.5.1` without we perform manual changes in these projects then, it means that; it will be a breaking change and requires a `MAJOR` Plugin version.

So, in this scenario, we should add to the PR a guide with the required steps that need to be done by the users to upgrade their projects built with `2.X.X` in order to make them work with the new `MAJOR` Plugin version `3.0.0`.

**IMPORTANT** The breaking changes cannot be applied in the V2 projects. So, beware and ensure it.

## Community, discussion and support

Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
Expand Down

0 comments on commit 8bce380

Please sign in to comment.