add readme to go/v3 scaffold templates

Signed-off-by: Bryce Palmer <bpalmer@redhat.com>

docs/book/src/SUMMARY.md

@@ -109,6 +109,8 @@
   - [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)
 

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

@@ -1,5 +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)
+  - [Declarative V1](declarative-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

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

@@ -0,0 +1,57 @@
+# go/v3
+
+Kubebuilder tool will scaffold the go/v3 plugin by default. This plugin is a composition of the plugins ` kustomize.common.kubebuilder.io/v1` and `base.go.kubebuilder.io/v3`. By using you can scaffold the default project which is a helper to construct sets of [controllers][controller-runtime]. 
+
+It basically scaffolds all the boilerplate code required to create and design controllers. Note that by following the [quickstart][quickstart] you will be using this plugin. 
+
+<aside class="note">
+
+<h1>Examples</h1>
+
+Samples are provided under the [testdata][testdata] directory of the Kubebuilder project. You can check samples using this plugin by looking at the `project-v3-<options>` projects under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
+
+</aside>
+
+## When to use it
+
+- If you are looking to scaffold Golang projects to develop projects using [controllers][controller-runtime]
+
+## How to use it ?
+
+As `go/v3` is the default plugin there is no need to explicitly mention to Kubebuilder to use this plugin. 
+
+To create a new project with the `go/v3` plugin the following command can be used:
+
+```sh
+kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project
+```
+All the other subcommands supported by the go/v3 plugin can be executed similarly.
+
+<aside class="note">
+
+<h1>Note</h1>
+
+Also, if you need you can explicitly inform the plugin via the option provided `--plugins=go/v3`.
+
+</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
+
+- To check how plugins are composited by looking at this definition in the [main.go][plugins-main].
+- Check the code implementation of the [base Golang plugin `base.go.kubebuilder.io/v3`][v3-plugin].
+- Check the code implementation of the [Kustomize/v1 plugin][kustomize-plugin].
+- Check [controller-runtime][controller-runtime] to know more about controllers.
+
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
+[quickstart]: ../quick-start.md
+[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata
+[plugins-main]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/cmd/main.go
+[v3-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/golang/v3
+[kustomize-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/common/kustomize/v1

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

@@ -0,0 +1,98 @@
+# Kustomize Plugin
+
+The kustomize plugin allows you to scaffold all kustomize manifests used to work with the language plugins such as `go/v2` and `go/v3`. 
+By using the kustomize plugin, you can create your own language plugins and ensure that you will have the same configurations 
+and features provided by it. 
+
+Note that projects such as [Operator-sdk][sdk] consume the Kubebuilder project as a lib and provide options to work with other languages
+like Ansible and Helm. The kustomize plugin allows them to easily keep a maintained configuration and ensure that all languages have
+the same configuration. It is also helpful if you are looking to provide nice plugins which will perform changes on top of
+what is scaffolded by default. With this approach we do not need to keep manually updating this configuration in all possible language plugins
+which uses the same and we are also
+able to create "helper" plugins which can work with many projects and languages.
+
+<aside class="note">
+<h1>Examples</h1>
+
+You can check the kustomize content by looking at the `config/` directory. Samples are provided under the [testdata][testdata]
+directory of the Kubebuilder project.
+
+</aside> 
+
+
+## When to use it
+
+- If you are looking to scaffold the kustomize configuration manifests for your own language plugin 
+
+## How to use it
+
+If you are looking to define that your language plugin should use kustomize use the [Bundle Plugin][bundle]
+to specify that your language plugin is a composition with your plugin responsable for scaffold
+all that is laguage specific and kustomize for its configuration, see: 
+
+```go
+	// Bundle plugin which built the golang projects scaffold by Kubebuilder go/v3
+	// The follow code is creating a new plugin with its name and version via composition
+	// You can define that one plugin is composite by 1 or Many others plugins
+	gov3Bundle, _ := plugin.NewBundle(golang.DefaultNameQualifier, plugin.Version{Number: 3},
+		kustomizecommonv1.Plugin{}, // scaffold the config/ directory and all kustomize files
+		golangv3.Plugin{}, // Scaffold the Golang files and all that specific for the language e.g. go.mod, apis, controllers
+	)
+```
+
+Also, with Kubebuilder, you can use kustomize alone via:
+
+```sh
+kubebuilder init --plugins=kustomize/v1 
+$ ls -la 
+total 24
+drwxr-xr-x   6 camilamacedo86  staff  192 31 Mar 09:56 .
+drwxr-xr-x  11 camilamacedo86  staff  352 29 Mar 21:23 ..
+-rw-------   1 camilamacedo86  staff  129 26 Mar 12:01 .dockerignore
+-rw-------   1 camilamacedo86  staff  367 26 Mar 12:01 .gitignore
+-rw-------   1 camilamacedo86  staff   94 31 Mar 09:56 PROJECT
+drwx------   6 camilamacedo86  staff  192 31 Mar 09:56 config
+```
+
+Or combined with the base language plugins:
+
+```sh
+# Provides the same scaffold of go/v3 plugin which is a composition (kubebuilder init --plugins=go/v3)
+kubebuilder init --plugins=kustomize/v1,base.go.kubebuilder.io/v3 --domain example.org --repo example.org/guestbook-operator 
+```
+
+## Subcommands
+
+The kustomize plugin implements the following subcommands:
+
+* init (`$ kubebuilder init [OPTIONS]`)
+* create api (`$ kubebuilder create api [OPTIONS]`)
+* create webhook (`$ kubebuilder create api [OPTIONS]`)
+
+<aside class="note">
+<h1>Create API and Webhook</h1>
+
+Its implementation for the subcommand create api will scaffold the kustomize manifests
+which are specific for each API, see [here][kustomize-create-api]. The same applies
+to its implementation for create webhook.
+
+</aside> 
+
+## Affected files
+
+The following scaffolds will be created or updated by this plugin:
+
+* `config/*`
+
+## Further resources
+
+* Check the kustomize [plugin implementation](https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/common/kustomize) 
+* Check the [kustomize documentation][kustomize-docs]
+* Check the [kustomize repository][kustomize-github]
+
+[sdk]:https://github.com/operator-framework/operator-sdk
+[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/
+[bundle]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugin/bundle.go
+[kustomize-create-api]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/common/kustomize/v1/scaffolds/api.go#L72-L84
+[kustomize-docs]: https://kustomize.io/
+[kustomize-github]: https://github.com/kubernetes-sigs/kustomize

pkg/plugins/golang/v3/scaffolds/init.go

@@ -112,5 +112,6 @@ func (s *initScaffolder) Scaffold() error {
 		},
 		&templates.Dockerfile{},
 		&templates.DockerIgnore{},
+		&templates.Readme{},
 	)
 }

pkg/plugins/golang/v3/scaffolds/internal/templates/readme.go

@@ -0,0 +1,129 @@
+/*
+Copyright 2022 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package templates
+
+import (
+	"fmt"
+	"strings"
+
+	"sigs.k8s.io/kubebuilder/v3/pkg/machinery"
+)
+
+var _ machinery.Template = &Readme{}
+
+// Readme scaffolds a README.md file
+type Readme struct {
+	machinery.TemplateMixin
+	machinery.BoilerplateMixin
+	machinery.ProjectNameMixin
+
+	License string
+}
+
+// SetTemplateDefaults implements file.Template
+func (f *Readme) SetTemplateDefaults() error {
+	if f.Path == "" {
+		f.Path = "README.md"
+	}
+
+	f.License = strings.Replace(
+		strings.Replace(string(f.Boilerplate), "/*", "", 1),
+		"*/", "", 1)
+
+	f.TemplateBody = fmt.Sprintf(readmeFileTemplate,
+		codeFence("sh", "kubectl apply -f config/samples/"),
+		codeFence("sh", "make docker-build docker-push IMG=<some-registry>/{{ .ProjectName }}:tag"),
+		codeFence("sh", "make deploy IMG=<some-registry>/{{ .ProjectName }}:tag"),
+		codeFence("sh", "make uninstall"),
+		codeFence("sh", "make undeploy"),
+		codeFence("sh", "make install"),
+		codeFence("sh", "make run"),
+		codeFence("sh", "make manifests"))
+
+	return nil
+}
+
+//nolint:lll
+const readmeFileTemplate = `# {{ .ProjectName }}
+// TODO(user): Add simple overview of use/purpose
+
+## Description
+// TODO(user): An in-depth paragraph about your project and overview of use
+
+## Getting Started
+You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
+**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster ` + "`kubectl cluster-info`" + ` shows).
+
+### Running on the cluster
+1. Install Instances of Custom Resources:
+
+%s
+
+2. Build and push your image to the location specified by ` + "`IMG`" + `:
+	
+%s
+	
+3. Deploy the controller to the cluster with the image specified by ` + "`IMG`" + `:
+
+%s
+
+### Uninstall CRDs
+To delete the CRDs from the cluster:
+
+%s
+
+### Undeploy controller
+UnDeploy the controller to the cluster:
+
+%s
+
+## Contributing
+// TODO(user): Add detailed information on how you would like others to contribute to this project
+
+### How it works
+This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
+
+It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) 
+which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster 
+
+### Test It Out
+1. Install the CRDs into the cluster:
+
+%s
+
+2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
+
+%s
+
+**NOTE:** You can also run this in one step by running: ` + "`make install run`" + `
+
+### Modifying the API definitions
+If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
+
+%s
+
+**NOTE:** Run ` + "`make --help`" + ` for more information on all potential ` + "`make`" + ` targets
+
+More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
+
+## License
+{{ .License }}
+`
+
+func codeFence(syntax string, code string) string {
+	return "```" + syntax + "\n" + code + "\n" + "```"
+}