Skip to content

Commit 7fc85be

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #2588 from Ashwin901/plugins-versioning-docs
📖 add to the website the plugins versioning documentation
2 parents 472cc07 + b0d0190 commit 7fc85be

File tree

3 files changed

+54
-44
lines changed

3 files changed

+54
-44
lines changed

‎VERSIONING.md

Lines changed: 0 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -58,49 +58,5 @@ take care of building and publishing the artifacts.
5858

5959
[envtest-ref]: https://book.kubebuilder.io/reference/artifacts.html
6060
[tools-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases
61-
62-
## Versioning
63-
64-
| Name | Example | Description |
65-
|--- |--- |--- |
66-
| Kubebuilder 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][kb-releases] page for binary releases. |
67-
| Project version | `"1"`, `"2"`, `"3"` | Project version defines the scheme of a `PROJECT` configuration file. This version is defined in a `PROJECT` file's `version`. |
68-
| Plugin version | `v2`, `v3` | Represents the version of an individual plugin, as well as the corresponding scaffolding that it generates. This version is defined in a plugin key, ex. `go.kubebuilder.io/v2`. See the [design doc][cli-plugins-versioning] for more details. |
69-
70-
### Incrementing versions
71-
72-
For more information on how Kubebuilder release versions work, see the [semver](https://semver.org/) documentation.
73-
74-
Project versions should only be increased if a breaking change is introduced in the PROJECT file scheme itself. Changes to the Go scaffolding or the Kubebuilder CLI *do not* affect project version.
75-
76-
Similarly, the introduction of a new plugin version might only lead to a new minor version 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 plugin version. See the plugins design doc [versioning section][cli-plugins-versioning]
77-
for more details on plugin versioning.
78-
79-
**NOTE:** the scheme for project version `"2"` was defined before the concept of plugins was introduced, so plugin `go.kubebuilder.io/v2` is implicitly used for those project types. Schema for project versions `"3"` and beyond define a `layout` key that informs the plugin system of which plugin to use.
80-
81-
## Introducing changes to plugins
82-
83-
Changes made to plugins only require a plugin version increase if and only if a change is made to a plugin
84-
that breaks projects scaffolded with the previous plugin version. Once a plugin version `vX` is stabilized (it doesn't
85-
have an "alpha" or "beta" suffix), a new plugin package should be created containing a new plugin with version
86-
`v(X+1)-alpha`. Typically this is done by (semantically) `cp -r pkg/plugins/golang/vX pkg/plugins/golang/v(X+1)` then updating
87-
version numbers and paths. All further breaking changes to the plugin should be made in this package; the `vX`
88-
plugin would then be frozen to breaking changes.
89-
90-
You must also add a migration guide to the [migrations](https://book.kubebuilder.io/migrations.html)
91-
section of the Kubebuilder book in your PR. It should detail the steps required
92-
for users to upgrade their projects from `vX` to `v(X+1)-alpha`.
93-
94-
### Example
95-
96-
Kubebuilder scaffolds projects with plugin `go.kubebuilder.io/v3` by default.
97-
98-
You create a feature that adds a new marker to the file `main.go` scaffolded by `init`
99-
that `create api` will use to update that file. The changes introduced in your feature
100-
would cause errors if used with projects built with plugins `go.kubebuilder.io/v2`
101-
without users manually updating their projects. Thus, your changes introduce a breaking change
102-
to plugin `go.kubebuilder.io`, and can only be merged into plugin version `v3-alpha`.
103-
This plugin's package should exist already.
104-
10561
[kb-releases]:https://github.com/kubernetes-sigs/kubebuilder/releases
10662
[cli-plugins-versioning]:docs/book/src/plugins/extending-cli.md#plugin-versioning

‎docs/book/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,7 @@
110110
- [Creating your own plugins](./plugins/creating-plugins.md)
111111
- [Available Plugins](./plugins/available-plugins.md)
112112
- [Declarative V1](./plugins/declarative-v1.md)
113+
- [Plugins Versioning](./plugins/plugins-versioning.md)
113114

114115
---
115116
[Appendix: The TODO Landing Page](./TODO.md)

‎docs/book/src/plugins/plugins-versioning.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Plugins Versioning
2+
3+
| Name | Example | Description |
4+
|----------|-------------|--------|
5+
| Kubebuilder 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][kb-releases] page for binary releases. |
6+
| Project version | `"1"`, `"2"`, `"3"` | Project version defines the scheme of a `PROJECT` configuration file. This version is defined in a `PROJECT` file's `version`. |
7+
| Plugin version | `v2`, `v3` | Represents the version of an individual plugin, as well as the corresponding scaffolding that it generates. This version is defined in a plugin key, ex. `go.kubebuilder.io/v2`. See the [design doc][cli-plugins-versioning] for more details. |
8+
9+
### Incrementing versions
10+
11+
For more information on how Kubebuilder release versions work, see the [semver][semver] documentation.
12+
13+
Project versions should only be increased if a breaking change is introduced in the PROJECT file scheme itself. Changes to the Go scaffolding or the Kubebuilder CLI *do not* affect project version.
14+
15+
Similarly, the introduction of a new plugin version might only lead to a new minor version 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 plugin version. See the plugins design doc [versioning section][cli-plugins-versioning]
16+
for more details on plugin versioning.
17+
18+
<aside class="note">
19+
20+
<h1>Why go/2 is different?</h1>
21+
22+
The scheme for project version `"2"` was defined before the concept of plugins was introduced, so plugin `go.kubebuilder.io/v2` is implicitly used for those project types. Schema for project versions `"3"` and beyond define a `layout` key that informs the plugin system of which plugin to use.
23+
24+
</aside>
25+
26+
## Introducing changes to plugins
27+
28+
Changes made to plugins only require a plugin version increase if and only if a change is made to a plugin
29+
that breaks projects scaffolded with the previous plugin version. Once a plugin version `vX` is stabilized (it doesn't
30+
have an "alpha" or "beta" suffix), a new plugin package should be created containing a new plugin with version
31+
`v(X+1)-alpha`. Typically this is done by (semantically) `cp -r pkg/plugins/golang/vX pkg/plugins/golang/v(X+1)` then updating
32+
version numbers and paths. All further breaking changes to the plugin should be made in this package; the `vX`
33+
plugin would then be frozen to breaking changes.
34+
35+
You must also add a migration guide to the [migrations][migrations]
36+
section of the Kubebuilder book in your PR. It should detail the steps required
37+
for users to upgrade their projects from `vX` to `v(X+1)-alpha`.
38+
39+
<aside class="note">
40+
41+
<h1>Example</h1>
42+
43+
Kubebuilder scaffolds projects with plugin `go.kubebuilder.io/v3` by default.
44+
45+
You create a feature that adds a new marker to the file `main.go` scaffolded by `init` that `create api` will use to update that file. The changes introduced in your feature would cause errors if used with projects built with plugins `go.kubebuilder.io/v2` without users manually updating their projects. Thus, your changes introduce a breaking change to plugin `go.kubebuilder.io`, and can only be merged into plugin version `v3-alpha`. This plugin's package should exist already.
46+
47+
</aside>
48+
49+
[design-doc]: ./extending-cli.md
50+
[cli-plugins-versioning]:./extending-cli.md#plugin-versioning
51+
[semver]: https://semver.org/
52+
[migrations]: ../migrations.md
53+
[kb-releases]:https://github.com/kubernetes-sigs/kubebuilder/releases

0 commit comments

Comments
 (0)