Merge branch 'master' into kustomize

Author: camilamacedo86

VERSIONING.md

@@ -58,49 +58,5 @@ take care of building and publishing the artifacts.
 
 [envtest-ref]: https://book.kubebuilder.io/reference/artifacts.html
 [tools-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases
-
-## Versioning
-
-|   Name	|   Example	|  Description |
-|---	|---	|---	|
-|  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. |
-|  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`. |
-|  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. |
-
-### Incrementing versions
-
-For more information on how Kubebuilder release versions work, see the [semver](https://semver.org/) documentation.
-
-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.
-
-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]
-for more details on plugin versioning.
-
-**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.
-
-## Introducing changes to plugins
-
-Changes made to plugins only require a plugin version increase if and only if a change is made to a plugin
-that breaks projects scaffolded with the previous plugin version. Once a plugin version `vX` is stabilized (it doesn't
-have an "alpha" or "beta" suffix), a new plugin package should be created containing a new plugin with version
-`v(X+1)-alpha`. Typically this is done by (semantically) `cp -r pkg/plugins/golang/vX pkg/plugins/golang/v(X+1)` then updating
-version numbers and paths. All further breaking changes to the plugin should be made in this package; the `vX`
-plugin would then be frozen to breaking changes.
-
-You must also add a migration guide to the [migrations](https://book.kubebuilder.io/migrations.html)
-section of the Kubebuilder book in your PR. It should detail the steps required
-for users to upgrade their projects from `vX` to `v(X+1)-alpha`.
-
-### Example
-
-Kubebuilder scaffolds projects with plugin `go.kubebuilder.io/v3` by default.
-
-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.
-
 [kb-releases]:https://github.com/kubernetes-sigs/kubebuilder/releases
 [cli-plugins-versioning]:docs/book/src/plugins/extending-cli.md#plugin-versioning

docs/book/src/SUMMARY.md

@@ -109,7 +109,10 @@
   - [Extending the CLI](./plugins/extending-cli.md)
   - [Creating your own plugins](./plugins/creating-plugins.md)
   - [Available Plugins](./plugins/available-plugins.md)
+    - [go/v3 plugin](./plugins/go-v3-plugin.md)
+    - [go/v2 plugin](./plugins/go-v2-plugin.md)
     - [Declarative V1](./plugins/declarative-v1.md)
+  - [Plugins Versioning](./plugins/plugins-versioning.md)
 
 ---  
 [Appendix: The TODO Landing Page](./TODO.md)

docs/book/src/cronjob-tutorial/testdata/project/api/v1/webhook_suite_test.go

@@ -71,7 +71,9 @@ var _ = BeforeSuite(func() {
 		},
 	}
 
-	cfg, err := testEnv.Start()
+	var err error
+	// cfg is defined in this file globally.
+	cfg, err = testEnv.Start()
 	Expect(err).NotTo(HaveOccurred())
 	Expect(cfg).NotTo(BeNil())
 

docs/book/src/cronjob-tutorial/testdata/project/controllers/suite_test.go

@@ -87,7 +87,9 @@ var _ = BeforeSuite(func() {
 	/*
 		Then, we start the envtest cluster.
 	*/
-	cfg, err := testEnv.Start()
+	var err error
+	// cfg is defined in this file globally.
+	cfg, err = testEnv.Start()
 	Expect(err).NotTo(HaveOccurred())
 	Expect(cfg).NotTo(BeNil())
 

docs/book/src/multiversion-tutorial/testdata/project/api/v1/webhook_suite_test.go

@@ -71,7 +71,9 @@ var _ = BeforeSuite(func() {
 		},
 	}
 
-	cfg, err := testEnv.Start()
+	var err error
+	// cfg is defined in this file globally.
+	cfg, err = testEnv.Start()
 	Expect(err).NotTo(HaveOccurred())
 	Expect(cfg).NotTo(BeNil())
 

docs/book/src/multiversion-tutorial/testdata/project/api/v2/webhook_suite_test.go

@@ -71,7 +71,9 @@ var _ = BeforeSuite(func() {
 		},
 	}
 
-	cfg, err := testEnv.Start()
+	var err error
+	// cfg is defined in this file globally.
+	cfg, err = testEnv.Start()
 	Expect(err).NotTo(HaveOccurred())
 	Expect(cfg).NotTo(BeNil())
 

docs/book/src/multiversion-tutorial/testdata/project/controllers/suite_test.go

@@ -58,7 +58,9 @@ var _ = BeforeSuite(func() {
 		ErrorIfCRDPathMissing: true,
 	}
 
-	cfg, err := testEnv.Start()
+	var err error
+	// cfg is defined in this file globally.
+	cfg, err = testEnv.Start()
 	Expect(err).NotTo(HaveOccurred())
 	Expect(cfg).NotTo(BeNil())
 

docs/book/src/plugins/available-plugins.md

@@ -1,6 +1,18 @@
-# Available Plugins
+# Available plugins
 
-This section details how to use the currently available plugins in Kubebuilder. 
+This section describes the plugins supported and shipped in with the Kubebuilder project.
 
   - [Declarative V1](declarative-v1.md)
-  - [Kustomize V1](kustomize-v1.md)
+  - [Kustomize V1](kustomize-v1.md)
+
+<aside class="note">
+
+<h1>But you can create your own plugins, see:</h1>
+
+- [Creating your own plugins][create-plugins]. 
+- [Plugins Phase 2][plugins-phase-2] - will allow users to use these external options as helpers to perform the scaffolds with the tool.
+
+</aside>
+
+[create-plugins]: creating-plugins.md
+[plugins-phase-2]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md

docs/book/src/plugins/declarative-v1.md

@@ -48,7 +48,7 @@ The following scaffolds will be created or updated by this plugin:
 * `channels/stable`
 * `Dockerfile`
 
-## Further ressources
+## Further resources
 
 * Read more about the [declarative pattern][kubebuilder-declarative-pattern]
 * Watch the KubeCon 2018 Video [Managing Addons with Operators][kubecon-video]

docs/book/src/plugins/go-v2-plugin.md

@@ -0,0 +1,51 @@
+# go/v2 plugin
+
+The `go/v2` plugin has the purpose to scaffold Golang projects to help users to build projects with [controllers][controller-runtime] and keep the backwards compatibility with the default scaffold made using Kubebuilder CLI `2.x.z` releases.   
+
+<node>
+
+You can check samples using this plugin by looking at the `project-v2-<options>` directories under the [testdata][testdata] projects on the root directory of the Kubebuilder project.
+
+</node>  
+
+## When should I use this plugin
+
+Only if you are looking to scaffold a project with the legacy layout. Otherwise, it is recommended you to use the default Golang version plugin. 
+
+<aside class="note warning">
+
+<h1> Note </h1>
+
+Be aware that this plugin version does not provide a scaffold compatible with the latest versions of the dependencies used in order to keep its backwards compatibility. 
+
+</aside>
+
+## How to use it ?
+
+To initialize a Golang project using the legacy layout and with this plugin run, e.g.:
+
+```sh
+kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project --plugins=go/v2
+```
+<aside class="note">
+
+<h1> Note </h1>
+
+By creating a project with this plugin, the PROJECT file scaffold will be using the previous schema (_project version 2_).  So that Kubebuilder CLI knows what plugin version was used and will call its subcommands such as `create api` and `create webhooks`.  Note that further Golang plugins versions use the new Project file schema, which tracks the information about what plugins and versions have been used so far. 
+
+</aside>
+
+## Subcommands supported by the plugin
+
+-  Init -  `kubebuilder init [OPTIONS]`
+-  Edit -  `kubebuilder edit [OPTIONS]`
+-  Create API -  `kubebuilder create api [OPTIONS]`
+-  Create Webhook - `kubebuilder create webhook [OPTIONS]`
+
+## Further resources
+
+- Check the code implementation of the [go/v2 plugin][v2-plugin].
+
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
+[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata
+[v2-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/golang/v2