demo-generate addition in makefile

🌱 fix (ci): fix lint issue: shadow: declaration of pluginCfg shadows declaration (#4725)

fix (ci): fix lint issue: shadow: declaration of pluginCfg shadows declaration

Fix plugin config test by resetting struct to avoid value reuse

Avoids test contamination caused by shared PluginConfig variable
by explicitly resetting it before decoding in each test case.
Also resolves shadowing linter errors reported by golangci-lint.

Updated 404 page

updated error page

updated book.toml

Delete docs/book/src/404.md

fix: use limited scoped error in generated main.go

Updated migration pages and added index for better navigation

removed prerequisite and verfication steps

changed the header

removed toc

fix: Use dynamic controller-runtime version in doc generator

Replace hardcoded controller-runtime version in hack/docs/internal/cronjob-tutorial/generate_cronjob.go with a reference to the ControllerRuntimeVersion constant from the scaffolding package.

This prevents the docs generation from breaking when the controller-runtime version is updated in the scaffolding logic, ensuring that `make generate-docs` remains stable across version bumps.

Update hack/docs/internal/cronjob-tutorial/generate_cronjob.go

Co-authored-by: Saan <94980910+sbin64@users.noreply.github.com>

Update hack/docs/internal/cronjob-tutorial/generate_cronjob.go

Co-authored-by: Kersten Burkhardt <kerstenk@gmail.com>

🌱 (chore): enable ginkgolinter forbid-spec-pollution to enforce isolated test specs

:seedling: (chore): enable ginkgolinter forbid-focus-container

:seedling: enable ginkgolinter forbid-focus-container

This PR adds the following configuration to `.golangci.yml`:

```yaml
linters-settings:
  ginkgolinter:
    forbid-focus-container: true
```

Enabling forbid-focus-container protects the code in the repository
against accident commiting of debug code. A contributeor may use
ginkgo's focus container (e.g. `FIt`, `FContext` etc. or by adding the
`Focus` decorator), in order to locally debug a specific test. Merging a
ginkgo's focus container will prevent running of all the other tests in
CI.

Signed-off-by: Nahshon Unna-Tsameret <nunnatsa@redhat.com>

📖 Fixed grammatical errors in designs doc (#4716)

Fixed grammatical error in designs doc

few more typos

🌱 (chore): replace errors.As() with MatchError() in error assertions

This update improves Gomega assertions by replacing `errors.As()` with `MatchError()` where the test intends to match specific error types rather than extract them.

This change simplifies the assertions and improves readability, aligning with idiomatic Gomega style.

Author: Kuzuri247

.golangci.yml

@@ -17,6 +17,8 @@ issues:
         - gosec
 
 linters-settings:
+  ginkgolinter:
+    forbid-spec-pollution: true
   govet:
     enable-all: true
     disable:
@@ -63,7 +65,8 @@ linters-settings:
       - name: bool-literal-in-expr
       - name: constant-logical-expr
       - name: comment-spacings
-
+  ginkgolinter:
+    forbid-focus-container: true
 linters:
   disable-all: true
   enable:

Makefile

@@ -84,6 +84,18 @@ generate-testdata: ## Update/generate the testdata in $GOPATH/src/sigs.k8s.io/ku
 	rm -rf testdata/
 	./test/testdata/generate.sh
 
+.PHONY: demo-generate
+demo-generate: ## Generate a new demo recording using Asciinema
+	@if ! command -v asciinema &> /dev/null; then \
+		echo "asciinema is not installed. Please install it first:"; \
+		echo "  https://asciinema.org/docs/installation"; \
+		exit 1; \
+	fi
+	@echo "Generating new demo recording..."
+	@cd scripts/demo && ./run.sh
+	@echo "Demo recording completed. The cast file is saved in scripts/demo/demo.cast"
+	@echo "You can now upload it to asciinema.org or embed it in the README"
+
 .PHONY: generate-docs
 generate-docs: ## Update/generate the docs
 	./hack/docs/generate.sh

README.md

@@ -47,7 +47,7 @@ Follow the [instructions](https://book.kubebuilder.io/quick-start.html#installat
 
 See the [Getting Started](https://book.kubebuilder.io/quick-start.html) documentation.
 
-![Quick Start](docs/gif/kb-demo.v3.11.1.svg)
+<script id="asciicast-id" src="https://asciinema.org/a/id.js" async></script> 
 
 Also, ensure that you check out the [Deploy Image](./docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md)
 Plugin. This plugin allows users to scaffold API/Controllers to deploy and manage an

designs/extensible-cli-and-scaffolding-plugins-phase-2.md

@@ -103,14 +103,14 @@ Note: If the name is ambiguous, then the qualified name `myexternalplugin.my.dom
 
 ### What Plugin system should we use
 
-I propose we use our own plugin system that passes JSON blobs back and forth across `stdin/stdout/stderr` and make this the only option for now as it’s a language-agnostic medium and it is easy to work with in most languages.
+I propose we use our own plugin system that passes JSON blobs back and forth across `stdin/stdout/stderr` and make this the only option for now as it's a language-agnostic medium and it is easy to work with in most languages.
 
-We came to the conclusion that a kubebuilder-specific plugin library should be written after evaluating plugin libraries such as the [built-in go-plugin library](https://golang.org/pkg/plugin/) and [Hashicorp’s plugin library](https://github.com/hashicorp/go-plugin):
+We came to the conclusion that a kubebuilder-specific plugin library should be written after evaluating plugin libraries such as the [built-in go-plugin library](https://golang.org/pkg/plugin/) and [Hashicorp's plugin library](https://github.com/hashicorp/go-plugin):
 
-* The built-in plugin library seems to be more suitable for in-tree plugins rather than out-of-tree plugins and it doesn’t offer cross-language support, thereby making it a non-starter.
-* Hashicorp’s go plugin system is more suitable than the built-in go-plugin library as it enables cross language/platform support. However, it is more suited for long running plugins as opposed to short lived plugins and the usage of protobuf could be overkill as we will not be handling 10s of 1000s of deserializations.
+* The built-in plugin library seems to be more suitable for in-tree plugins rather than out-of-tree plugins and it doesn't offer cross-language support, thereby making it a non-starter.
+* Hashicorp's go plugin system is more suitable than the built-in go-plugin library as it enables cross-language/platform support. However, it is more suited for long-running plugins as opposed to short-lived plugins and the usage of protobuf could be overkill as we will not be handling 10s of 1000s of deserializations.
 
-In the future, if a need arises (for example, users are hitting performance issues), we can then explore the possibility of using the Hashicorp’s go plugin library. From a design standpoint, to leave it architecturally open, I propose using a `type` field in the PROJECT file to potentially allow other plugin libraries in the future and make this a seperate field in the PROJECT file per plugin; and this field determines how the `universe` will be passed for a given plugin. However, for the sake of simplicity in initial design and not to introduce any breaking changes as Project version 3 would suffice for our needs, this option is out of scope in this proposal.
+In the future, if a need arises (for example, users are hitting performance issues), we can then explore the possibility of using the Hashicorp's go plugin library. From a design standpoint, to leave it architecturally open, I propose using a `type` field in the PROJECT file to potentially allow other plugin libraries in the future and make this a separate field in the PROJECT file per plugin; and this field determines how the `universe` will be passed for a given plugin. However, for the sake of simplicity in initial design and not to introduce any breaking changes as Project version 3 would suffice for our needs, this option is out of scope in this proposal.
 
 ### Project configuration
 
@@ -165,14 +165,14 @@ resources:
 
 ![Kubebuilder to external plugins sequence diagram](https://github.com/rashmigottipati/POC-Phase2-Plugins/blob/main/docs/externalplugins-sequence-diagram.png)
 
-* What to pass between `kubebuilder` and an external plugin?
+* What should be passed between `kubebuilder` and an external plugin?
 
 Message passing between `kubebuilder` and the external plugin will occur through a request / response mechanism. The `PluginRequest` will contain information that `kubebuilder` sends *to* the external plugin. The `PluginResponse` will contain information that `kubebuilder` receives *from* the external plugin.
 
-The following scenarios shows what `kubebuilder` will send/receive to the external plugin:
+The following scenarios show what `kubebuilder` will send/receive to the external plugin:
 
 * `kubebuilder` to external plugin:
-  * `kubebuilder` constructs a `PluginRequest` that contains the `Command` (such as `init`, `create api`, or `create webhook`), `Args` containing all the raw flags from the CLI request and license boilerplate without comment delimiters, and an empty `Universe` that contains the current virtual state of file contents that is not written to the disk yet. `kubebuilder` writes the `PluginRequest` through `stdin`.
+  * `kubebuilder` constructs a `PluginRequest` that contains the `Command` (such as `init`, `create api`, or `create webhook`), `Args` containing all the raw flags from the CLI request and license boilerplate without comment delimiters, and an empty `Universe` that contains the current virtual state of file contents that are not written to disk yet. `kubebuilder` writes the `PluginRequest` through `stdin`.
 
 * External plugin to `kubebuilder`:
   * The plugin reads the `PluginRequest` through its `stdin` and processes the request based on the `Command` that was sent. If the `Command` doesn't match what the plugin supports, it writes back an error immediately without any further processing. If the `Command` matches what the plugin supports, it constructs a `PluginResponse` containing the `Command` that was executed by the plugin, and modified `Universe` based on the new files that were scaffolded by the external plugin, `Error` and `ErrorMsg` that add any error information, and writes the `PluginResponse` back to `kubebuilder` through `stdout`.
@@ -314,7 +314,7 @@ What happens when the above is invoked?
 
 #### User specified file paths
 
-A user will provide a list of file paths for `kubebuilder` to discover the plugins in. We will define a variable `KUBEBUILDER_PLUGINS_DIRS` that will take a list of file paths to search for the plugin name. It will also have a default value to search in, in case no file paths are provided. It will search for the plugin name that was provided to the `--plugins` flag in the CLI. `kubebuilder` will recursively search for all file paths until the plugin name is found and returns the successful match, and if it doesn’t exist, it returns an error message that the plugin is not found in the provided file paths. Also use the host system mechanism for PATH separation.
+A user will provide a list of file paths for `kubebuilder` to discover the plugins in. We will define a variable `KUBEBUILDER_PLUGINS_DIRS` that will take a list of file paths to search for the plugin name. It will also have a default value to search in, in case no file paths are provided. It will search for the plugin name that was provided to the `--plugins` flag in the CLI. `kubebuilder` will recursively search for all file paths until the plugin name is found and returns the successful match, and if it doesn't exist, it returns an error message that the plugin is not found in the provided file paths. Also use the host system mechanism for PATH separation.
 
 * Alternatively, this could be handled in a way that [helm kustomize plugin](https://helm.sh/docs/topics/advanced/#post-rendering) discovers the plugin based on the non-existence of a separator in the path provided, in which case `kubebuilder` will search in `$PATH`, otherwise resolve any relative paths to a fully qualified path.
 
@@ -330,9 +330,9 @@ A user will provide a list of file paths for `kubebuilder` to discover the plugi
 Another approach is adding plugin executables with a prefix `kubebuilder-` followed by the plugin name to the PATH variable. This will enable `kubebuilder` to traverse through the PATH looking for the plugin executables starting with the prefix `kubebuilder-` and matching by the plugin name that was provided in the CLI. Furthermore, a check should be added to verify that the match is an executable or not and return an error if it's not an executable. This approach provides a lot of flexibility in terms of plugin discovery as all the user needs to do is to add the plugin executable to the PATH and `kubebuilder` will discover it.
 
 * Pros
-  * `kubectl` and `git` follow the same approach for discovering plugins, so there’s prior art.
+  * `kubectl` and `git` follow the same approach for discovering plugins, so there's prior art.
 
-  * There’s a lot of flexibility in just dropping plugin binaries to PATH variable and enabling the discovery without having to enforce any other constraints on the placements of the plugins.
+  * There's a lot of flexibility in just dropping plugin binaries to PATH variable and enabling the discovery without having to enforce any other constraints on the placements of the plugins.
 
 * Cons
   * Enumerating the list of all available plugins might be a bit tough compared to having a single folder with the list of available plugins and having to enumerate those.

designs/helper_to_upgrade_projects_by_rescaffolding.md

@@ -29,16 +29,16 @@ the projects might have bug fixes and new incremental features added to the
 templates which will result in changes to the files that are generated by
 the tool for new projects.
 
-In this case, you used previously the tool to generate the project
+In this case, you previously used the tool to generate the project
 and now would like to update your project with the latest changes
 provided for the same plugin version. Therefore, you will need to:
 
 - Download and install KubeBuilder binary ( latest / upper release )
 - You will run the command in the root directory of your project: `kubebuilder alpha generate`
 - Then, the command will remove the content of your local directory and re-scaffold the project from the scratch
 - It will allow you to compare your local branch with the remote branch of your project to re-add the code on top OR
-  if you do not use the flag `--no-backup` then you can compare the local directory with the copy of your project
-  copied to the path `.backup/project-name/` before the re-scaffold be done.
+  if you do not use the flag `--no-backup`, then you can compare the local directory with the copy of your project
+  copied to the path `.backup/project-name/` before the re-scaffold is done.
 - Therefore, you can run make all and test the final result. You will have after all your project updated.
 
 **To update the project with major changes provided**
@@ -66,16 +66,16 @@ A common scenario is to upgrade the project based on the newer Kubebuilder. The
 The proposed command will automate the process at maximum, therefore helping operator authors with minimizing the manual effort.
 
 The main motivation of this proposal is to provide a helper for upgrades and
-make less painful this process. Examples:
+make this process less painful. Examples:
 
 - See the discussion [How to regenerate scaffolding?](https://github.com/kubernetes-sigs/kubebuilder/discussions/2864)
 - From [slack channel By Paul Laffitte](https://kubernetes.slack.com/archives/CAR30FCJZ/p1675166014762669)
 
 ### Goals
 
 - Help users upgrade their project with the latest changes
-- Help users to re-scaffold projects from scratch based on what was done previously with the tool
-- Make less painful the process to upgrade
+- Help users re-scaffold projects from scratch based on what was done previously with the tool
+- Make the upgrade process less painful
 
 ### Non-Goals
 
@@ -106,7 +106,7 @@ kubebuilder alpha generate \
 - no-backup: [Optional] If not informed then, the current directory should be copied to the path `.backup/project-name`
 - backup: [Optional] If not informed then, the backup will be copied to the path `.backup/project-name`
 - plugins:  [Optional] If not informed then, it is the same plugin chain available in the layout field
-- binary: [Optional] If not informed then, the command will use KubeBuilder binary installed globaly.
+- binary: [Optional] If not informed then, the command will use KubeBuilder binary installed globally.
 
 > Note that the backup created in the current directory must be prefixed with `.`. Otherwise the tool
 will not able to perform the scaffold to create a new project from the scratch.
@@ -116,12 +116,12 @@ This command would mainly perform the following operations:
 - 1. Check the flags
 - 2. If the backup flag be used, then check if is a valid path and make a backup of the current project
 - 3. Copy the whole current directory to `.backup/project-name`
-- 4. Ensure that the output path is clean. By default it is the current directory project where the project was scaffolded previously and it should be cleaned up before to do the re-scaffold.
+- 4. Ensure that the output path is clean. By default it is the current directory project where the project was scaffolded previously and it should be cleaned up before doing the re-scaffold.
 Only the content under `.backup/project-name` should be kept.
-- 4. Read the [PROJECT config][project-config]
-- 5. Re-run all commands using the KubeBuilder binary to recreate the project in the output directory
+- 5. Read the [PROJECT config][project-config]
+- 6. Re-run all commands using the KubeBuilder binary to recreate the project in the output directory
 
-The command should also provide a comprensive help with examples of the proposed workflows. So that, users
+The command should also provide comprehensive help with examples of the proposed workflows. So that, users
 are able to understand how to use it when run `--help`.
 
 ### User Stories

designs/integrating-kubebuilder-and-osdk.md

@@ -2,12 +2,11 @@
 |---------------|---------------|-------------|-------|
 | @joelanford |  Sep 6, 2019  | implemented | -     |
 
-Integrating Kubebuilder and Operator SDK
-========================================
+# Integrating Kubebuilder and Operator SDK
 
 ## Goal
 
-To unite Kubebuilder and Operator SDK around Kubebuilder’s project scaffolding, to move Operator SDK’s Go operator features upstream, where appropriate, and to join forces on maintaining Kubebuilder so that both Kubebuilder and Operator SDK support the same project structure and command line interface for Go-based operators.
+To unite Kubebuilder and Operator SDK around Kubebuilder's project scaffolding, to move Operator SDK's Go operator features upstream, where appropriate, and to join forces on maintaining Kubebuilder so that both Kubebuilder and Operator SDK support the same project structure and command line interface for Go-based operators.
 
 ## Background
 
@@ -26,17 +25,17 @@ The Kubebuilder and Operator SDK contributors created a [GitHub project][kb-osdk
 ### Upstream code from Operator SDK
 
 The Operator SDK project contains various features that can be used by Go operator developers regardless of whether the project is based on Kubebuilder or Operator SDK. These features will be upstreamed into `kubebuilder`, `controller-runtime`, and `controller-tools`, where appropriate. These include:
-* a `DynamicRESTMapper` that enables an operator to dynamically and automatically discover new CRDs added to the cluster after the operator has started
-* a `GenerationChangedPredicate` that can trigger reconciliation events when a resource's `metadata.generation` field has changed.
-* flags and helpers that can be used to provide more fine-grained configuration when constructing the default `zap`-based logger.
+* A `DynamicRESTMapper` that enables an operator to dynamically and automatically discover new CRDs added to the cluster after the operator has started
+* A `GenerationChangedPredicate` that can trigger reconciliation events when a resource's `metadata.generation` field has changed
+* Flags and helpers that can be used to provide more fine-grained configuration when constructing the default `zap`-based logger
 
 The Operator SDK contributors plan to begin conducting all development of Go operator related code in upstream Kubebuilder (and related projects) and to spend more time helping the Kubebuilder contributors maintain these projects.
 
 ### Prototypes
 
 To make Kubebuilder more extensible, the community has been discussing a proposal to add extension points to Kubebuilder to support different operator patterns. One example of an operator pattern is the [addon pattern][addon-pattern-pr] that uses an existing library to instantiate an opinionated API and controller.
 
-More broadly, the idea is to add support for executable plugin-based extensions that can modify Kubebuilder’s base scaffolding before files are written to disk so that the project (e.g. Go code, kustomize templates, the project Makefile and Dockerfile) can have customized content provided by an extension.
+More broadly, the idea is to add support for executable plugin-based extensions that can modify Kubebuilder's base scaffolding before files are written to disk so that the project (e.g. Go code, kustomize templates, the project Makefile and Dockerfile) can have customized content provided by an extension.
 
 ### Documentation
 

designs/simplified-scaffolding.md

@@ -137,8 +137,8 @@ they think it is, we're probably better served coming up with a standard
 "can I create this example YAML file".
 
 Furthermore, since the structure is quite convoluted, it makes it more
-difficult to write examples, since the actual code we care about ends up
-scattered deep in a folder structure.
+difficult to write examples, as the actual code we care about ends up
+scattered deep in the folder structure.
 
 ### Lack of Builder
 

designs/template.md

@@ -2,8 +2,7 @@
 |---------------|---------------|-------------|---|
 | @name | date | Implementable | - |
 
-Title of the Design/Proposal
-===================
+# Title of the Design/Proposal
 
 <!-- Describe your change here.  This is purposefully freeform: we want
 enough information to evaluate the design, but not so much that you're

docs/book/book.toml

@@ -5,7 +5,7 @@ src = "src"
 title = "The Kubebuilder Book"
 
 [output.html]
-curly-quotes = true
+smart-punctuation = true
 additional-css = ["theme/css/markers.css", "theme/css/custom.css", "theme/css/version-dropdown.css"]
 git-repository-url = "https://github.com/kubernetes-sigs/kubebuilder"
 edit-url-template = "https://github.com/kubernetes-sigs/kubebuilder/edit/master/docs/book/{path}"