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 13df241
Showing 1 changed file with 30 additions and 0 deletions.
30 changes: 30 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,36 @@ 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, you can find the design doc [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` | You will find this versions in the [releases](https://github.com/kubernetes-sigs/kubebuilder/releases) page of this repo. This versions represents the release tags of this project. |
| Plugin Versions | `go.kubebuilder.io/v2.0.0` | The plugins versions represents the code source of the plugin used to generate the projects with the CLI tool. |

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

```
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards compatible manner, and
- PATCH version when you make backwards compatible bug fixes.
```

## 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 new content and/or file it probably will not be and breaking change.

To keep the sanity here and simplify it, let's 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 can upgrade their project built with `2.X.X` to 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 13df241

Please sign in to comment.