Skip to content

Commit

Permalink
📖 remove traling spaces of all docs
Browse files Browse the repository at this point in the history
  • Loading branch information
camilamacedo86 committed Mar 29, 2024
1 parent 1ceed81 commit a2fc1b6
Show file tree
Hide file tree
Showing 90 changed files with 2,592 additions and 2,592 deletions.
28 changes: 14 additions & 14 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,27 +87,27 @@ To fully test the proposed plugin:
1. Create a new package(folder) under `test/e2e/<your-plugin>`.
2. Create [e2e_suite_test.go](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/v4/e2e_suite_test.go), which imports the necessary testing framework.
3. Create `generate_test.go` ([ref](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/v4/generate_test.go)). That should:
- Introduce/Receive a `TextContext` instance
- Trigger the plugin's bound subcommands. See [Init](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L213), [CreateAPI](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/test/e2e/utils/test_context.go#L222)
- Use [PluginUtil](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/pkg/plugin/util) to verify the scaffolded outputs. See [InsertCode](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/pkg/plugin/util/util.go#L67), [ReplaceInFile](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/pkg/plugin/util/util.go#L196), [UncommendCode](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/pkg/plugin/util/util.go#L86)
- Introduce/Receive a `TextContext` instance
- Trigger the plugin's bound subcommands. See [Init](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L213), [CreateAPI](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/test/e2e/utils/test_context.go#L222)
- Use [PluginUtil](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/pkg/plugin/util) to verify the scaffolded outputs. See [InsertCode](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/pkg/plugin/util/util.go#L67), [ReplaceInFile](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/pkg/plugin/util/util.go#L196), [UncommendCode](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/pkg/plugin/util/util.go#L86)
4. Create `plugin_cluster_test.go` ([ref](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/v4/plugin_cluster_test.go)). That should:

- 4.1. Setup testing environment, e.g:
- 4.1. Setup testing environment, e.g:

- Cleanup environment, create temp dir. See [Prepare](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L97)
- If your test will cover the provided features then, ensure that you install prerequisites CRDs: See [InstallCertManager](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L138), [InstallPrometheusManager](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/test/e2e/utils/test_context.go#L171)
- Cleanup environment, create temp dir. See [Prepare](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L97)
- If your test will cover the provided features then, ensure that you install prerequisites CRDs: See [InstallCertManager](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L138), [InstallPrometheusManager](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.6.0/test/e2e/utils/test_context.go#L171)

- 4.2. Run the function from `generate_test.go`.
- 4.2. Run the function from `generate_test.go`.

- 4.3. Further make sure the scaffolded output works, e.g:
- 4.3. Further make sure the scaffolded output works, e.g:

- Execute commands in your `Makefile`. See [Make](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L240)
- Temporary load image of the testing controller. See [LoadImageToKindCluster](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L283)
- Call Kubectl to validate running resources. See [utils.Kubectl](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/test/e2e/utils#Kubectl)
- Execute commands in your `Makefile`. See [Make](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L240)
- Temporary load image of the testing controller. See [LoadImageToKindCluster](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L283)
- Call Kubectl to validate running resources. See [utils.Kubectl](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/test/e2e/utils#Kubectl)

- 4.4. Delete temporary resources after testing exited, e.g:
- Uninstall prerequisites CRDs: See [UninstallPrometheusOperManager](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L183)
- Delete temp dir. See [Destroy](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L255)
- 4.4. Delete temporary resources after testing exited, e.g:
- Uninstall prerequisites CRDs: See [UninstallPrometheusOperManager](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L183)
- Delete temp dir. See [Destroy](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/utils/test_context.go#L255)

5. Add the command in [test/e2e/plugin](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/test/e2e/setup.sh#L65) to run your testing code:

Expand Down
138 changes: 69 additions & 69 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,112 +6,112 @@ project and its various components.
## Overarching

* **Libraries Over Code Generation**: Generated code is messy to maintain,
hard for humans to change and understand, and hard to update. Library
code is easy to update (just increase your dependency version), easier
to version using existing mechanisms, and more concise.
hard for humans to change and understand, and hard to update. Library
code is easy to update (just increase your dependency version), easier
to version using existing mechanisms, and more concise.

* **Copy-pasting is bad**: Copy-pasted code suffers from similar problems
as code generation, except more acutely. Copy-pasted code is nearly
impossible to easy update, and frequently suffers from bugs and
misunderstandings. If something is being copy-pasted, it should
refactored into a library component or remote
[kustomize](https://sigs.k8s.io/kustomize) base.
as code generation, except more acutely. Copy-pasted code is nearly
impossible to easy update, and frequently suffers from bugs and
misunderstandings. If something is being copy-pasted, it should
refactored into a library component or remote
[kustomize](https://sigs.k8s.io/kustomize) base.

* **Common Cases Should Be Easy**: The 80-90% common cases should be
simple and easy for users to understand.
simple and easy for users to understand.

* **Uncommon Cases Should Be Possible**: There shouldn't be situations
where it's downright impossible to do something within
controller-runtime or controller-tools. It may take extra digging or
coding, and it may involve interoperating with lower-level components,
but it should be possible without unreasonable friction.
where it's downright impossible to do something within
controller-runtime or controller-tools. It may take extra digging or
coding, and it may involve interoperating with lower-level components,
but it should be possible without unreasonable friction.

## Kubebuilder

* **Kubebuilder Has Opinions**: Kubebuilder exists as an opinionated
project generator. It should strive to give users a reasonable project
layout that's simple enough to understand when getting started, but
provides room to grow. It might not match everyone's opinions, but it
should strive to be useful to most.
project generator. It should strive to give users a reasonable project
layout that's simple enough to understand when getting started, but
provides room to grow. It might not match everyone's opinions, but it
should strive to be useful to most.

* **Batteries Included**: Kubebuilder projects should contain enough
deployment information to reasonably develop and run the scaffolded
project. This includes testing, deployment files, and development
infrastructure to go from code to running containers.
deployment information to reasonably develop and run the scaffolded
project. This includes testing, deployment files, and development
infrastructure to go from code to running containers.

## controller-tools and controller-runtime

* **Sufficient But Composable**: controller-tools and controller-runtime
should be sufficient for building a custom controller by hand. While
scaffolding and additional libraries may make life easier, building
without should be as painless as possible. That being said, they should
strive to be usable as building blocks for higher-level libraries as
well.
should be sufficient for building a custom controller by hand. While
scaffolding and additional libraries may make life easier, building
without should be as painless as possible. That being said, they should
strive to be usable as building blocks for higher-level libraries as
well.

* **Self-Sufficient Docs**: controller-tools and controller-runtime should
strive to have self-sufficient docs (i.e. documentation that doesn't
require reading other libraries' documentation for common use cases).
Examples should be plentiful.
strive to have self-sufficient docs (i.e. documentation that doesn't
require reading other libraries' documentation for common use cases).
Examples should be plentiful.

* **Contained Arcana**: Developers should not need to be experts in
Kubernetes API machinery to develop controllers, but those familiar with
Kubernetes API machinery should not feel out of place. Abstractions
should be intuitive to new users but feel familiar to experienced ones.
Abstractions should embrace the concepts of Kubernetes (e.g. declarative
idempotent reconcilers) while simplifying the details.
Kubernetes API machinery to develop controllers, but those familiar with
Kubernetes API machinery should not feel out of place. Abstractions
should be intuitive to new users but feel familiar to experienced ones.
Abstractions should embrace the concepts of Kubernetes (e.g. declarative
idempotent reconcilers) while simplifying the details.

## controller-runtime

* **Abstractions Should Be Layered**: Abstractions should be built on top
of lower layers, such that advanced users can write custom logic while
still working within the existing model. For instance, the controller
builder is built on top of the event, source, and handler helpers, which
are in turn built for use with the event, source, and handler
interfaces.
of lower layers, such that advanced users can write custom logic while
still working within the existing model. For instance, the controller
builder is built on top of the event, source, and handler helpers, which
are in turn built for use with the event, source, and handler
interfaces.

* **Repetitive Stress Injuries Are Bad**:
When possible, commonly used pieces should be exposed in a way that
enables clear, concise code. This includes aliasing groups of
functionality under "alias" or "prelude" packages to avoid having 40
lines of imports, including common idioms as flexible helpers, and
infering resource information from the user's object types in client
code.
When possible, commonly used pieces should be exposed in a way that
enables clear, concise code. This includes aliasing groups of
functionality under "alias" or "prelude" packages to avoid having 40
lines of imports, including common idioms as flexible helpers, and
infering resource information from the user's object types in client
code.

* **A Little Bit of Magic Goes a Long Way**: In absence of generics,
reflection is acceptable, especially when it leads to clearer, conciser
code. However, when possible interfaces that use reflection should be
designed to avoid requiring the end-developer to use type assertions,
string splitting, which are error-prone and repetitive. These should be
dealt with inside controller-runtime internals.
reflection is acceptable, especially when it leads to clearer, conciser
code. However, when possible interfaces that use reflection should be
designed to avoid requiring the end-developer to use type assertions,
string splitting, which are error-prone and repetitive. These should be
dealt with inside controller-runtime internals.

* **Defaults Over Constructors**: When not a huge performance impact,
favor auto-defaulting and `Options` structs over constructors.
Constructors quickly become unclear due to lack of names associated
with values, and don't work well with optional values.
favor auto-defaulting and `Options` structs over constructors.
Constructors quickly become unclear due to lack of names associated
with values, and don't work well with optional values.

## Development

* **Words Are Better Than Letters**: Don't abbreviate variable names
unless it's blindingly obvious what they are (e.g. `ctx` for `Context`).
Single- and double-letter method receivers are acceptable, but single-
and double-letter variables quickly become confusing the longer a code
block gets.
unless it's blindingly obvious what they are (e.g. `ctx` for `Context`).
Single- and double-letter method receivers are acceptable, but single-
and double-letter variables quickly become confusing the longer a code
block gets.

* **Well-commented code**: Code should be commented and given Godocs, even
private methods and functions. It may *seem* obvious what they do at the
time and why, but you might forget, and others will certainly come along.
private methods and functions. It may *seem* obvious what they do at the
time and why, but you might forget, and others will certainly come along.

* **Test Behaviors**: Test cases should be comprehensible as sets of
expected behaviors. Test cases read without code (e.g. just using `It`,
`Describe`, `Context`, and `By` lines) should still be able to explain
what's required of the tested interface. Testing behaviors makes
internal refactors easier, and makes reading tests easier.
expected behaviors. Test cases read without code (e.g. just using `It`,
`Describe`, `Context`, and `By` lines) should still be able to explain
what's required of the tested interface. Testing behaviors makes
internal refactors easier, and makes reading tests easier.

* **Real Components Over Mocks**: Avoid mocks and recording actions. Mocks
tend to be brittle and gradually become more complicated over time (e.g.
fake client implementations tend to grow into poorly-written, incomplete
API servers). Recording of actions tends to lead to brittle tests that
requires changes during refactors. Instead, test that the end desired
state is correct. Test the way the world should be, without caring how
it got there, and provide easy ways to set up the real components so
that mocks aren't required.
tend to be brittle and gradually become more complicated over time (e.g.
fake client implementations tend to grow into poorly-written, incomplete
API servers). Recording of actions tends to lead to brittle tests that
requires changes during refactors. Instead, test that the end desired
state is correct. Test the way the world should be, without caring how
it got there, and provide easy ways to set up the real components so
that mocks aren't required.
30 changes: 15 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,10 @@ Kubebuilder is developed on top of the [controller-runtime][controller-runtime]
### Kubebuilder is also a library

Kubebuilder is extensible and can be used as a library in other projects.
[Operator-SDK][operator-sdk] is a good example of a project that uses Kubebuilder as a library.
[Operator-SDK][operator-sdk] is a good example of a project that uses Kubebuilder as a library.
[Operator-SDK][operator-sdk] uses the plugin feature to include non-Go operators _e.g. operator-sdk's Ansible and Helm-based language Operators_.

To learn more see [how to create your own plugins][your-own-plugins].
To learn more see [how to create your own plugins][your-own-plugins].

### Installation

Expand All @@ -39,9 +39,9 @@ See the [Getting Started](https://book.kubebuilder.io/quick-start.html) document

![Quick Start](docs/gif/kb-demo.v3.11.1.svg)

Also, ensure that you check out the [Deploy Image](https://book.kubebuilder.io/plugins/deploy-image-plugin-v1-alpha.html)
Plugin. This plugin allows users to scaffold API/Controllers to deploy and manage an
Operand (image) on the cluster following the guidelines and best practices. It abstracts the
Also, ensure that you check out the [Deploy Image](https://book.kubebuilder.io/plugins/deploy-image-plugin-v1-alpha.html)
Plugin. This plugin allows users to scaffold API/Controllers to deploy and manage an
Operand (image) on the cluster following the guidelines and best practices. It abstracts the
complexities of achieving this goal while allowing users to customize the generated code.

## Documentation
Expand Down Expand Up @@ -93,11 +93,11 @@ Provide clean library abstractions with clear and well exampled godocs.
## Techniques

- Provide higher level libraries on top of low level client libraries
- Protect developers from breaking changes in low level libraries
- Start minimal and provide progressive discovery of functionality
- Provide sane defaults and allow users to override when they exist
- Protect developers from breaking changes in low level libraries
- Start minimal and provide progressive discovery of functionality
- Provide sane defaults and allow users to override when they exist
- Provide code generators to maintain common boilerplate that can't be addressed by interfaces
- Driven off of `//+` comments
- Driven off of `//+` comments
- Provide bootstrapping commands to initialize new packages

## Versioning and Releasing
Expand All @@ -107,11 +107,11 @@ See [VERSIONING.md](VERSIONING.md).
## Troubleshooting

- ### Bugs and Feature Requests:
If you have what looks like a bug, or you would like to make a feature request, please use the [Github issue tracking system.](https://github.com/kubernetes-sigs/kubebuilder/issues)
If you have what looks like a bug, or you would like to make a feature request, please use the [Github issue tracking system.](https://github.com/kubernetes-sigs/kubebuilder/issues)
Before you file an issue, please search existing issues to see if your issue is already covered.

- ### Slack
For realtime discussion, you can join the [#kubebuilder](https://slack.k8s.io/#kubebuilder) slack channel. Slack requires registration, but the Kubernetes team is open invitation to anyone to register here. Feel free to come and ask any questions.
For realtime discussion, you can join the [#kubebuilder](https://slack.k8s.io/#kubebuilder) slack channel. Slack requires registration, but the Kubernetes team is open invitation to anyone to register here. Feel free to come and ask any questions.

## Contributing

Expand All @@ -121,18 +121,18 @@ Before starting any work, please either comment on an existing issue, or file a

## Supportability

Currently, Kubebuilder officially supports OSX and Linux platforms.
So, if you are using a Windows OS you may find issues. Contributions towards
Currently, Kubebuilder officially supports OSX and Linux platforms.
So, if you are using a Windows OS you may find issues. Contributions towards
supporting Windows are welcome.

### Apple Silicon

Apple Silicon (`darwin/arm64`) support begins with the `go/v4` plugin.

## Community Meetings

The following meetings happen biweekly:

- Kubebuilder Meeting

You are more than welcome to attend. For further info join to [kubebuilder@googlegroups.com](https://groups.google.com/g/kubebuilder).
Expand Down

0 comments on commit a2fc1b6

Please sign in to comment.