This document describes how to contribute to the project.
Kubernetes projects require that you sign a Contributor License Agreement (CLA) before we can accept your pull requests.
Please see https://git.k8s.io/community/CLA.md for more info.
- go version v1.21+.
- docker version 17.03+.
- kubectl version v1.11.3+.
- kustomize v3.1.0+
- Access to a Kubernetes v1.11.3+ cluster.
- Submit an issue describing your proposed change to the repo in question.
- The repo owners will respond to your issue promptly.
- If your proposed change is accepted, and you haven't already done so, sign a Contributor License Agreement (see details above).
- Fork the desired repo, develop and test your code changes.
- Submit a pull request.
In addition to the above steps, we adhere to the following best practices to maintain consistency and efficiency in our project:
- Single Commit per PR: Each Pull Request (PR) should contain only one commit. This approach simplifies tracking changes and makes the history more readable.
- One Issue per PR: Each PR should address a single specific issue or need. This helps in streamlining our workflow and makes it easier to identify and resolve problems such as revert the changes if required.
For more detailed guidelines, refer to the Kubernetes Contributor Guide.
Note that, by building the kubebuilder from the source code we are allowed to test the changes made locally.
- Run the following command to clone your fork of the project locally in the dir /src/sigs.k8s.io/kubebuilder
$ git clone [email protected]:<user>/kubebuilder.git $GOPATH/src/sigs.k8s.io/kubebuilder
- Ensure you activate module support before continue (
$ export GO111MODULE=on
) - Run the command
make install
to create a bin with the source code
NOTE In order to check the local environment run make test-unit
.
- Run the script
make generate
to update/generate the mock data used in the e2e test in$GOPATH/src/sigs.k8s.io/kubebuilder/testdata/
- Run
make test-unit test-e2e-local
- e2e tests use
kind
andsetup-envtest
. If you want to bring your own binaries, place them in$(go env GOPATH)/bin
.
IMPORTANT: The make generate
is very helpful. By using it, you can check if good part of the commands still working successfully after the changes. Also, note that its usage is a pre-requirement to submit a PR.
Following the targets that can be used to test your changes locally.
Command | Description | Is called in the CI? |
---|---|---|
make test-unit | Runs go tests | no |
make test | Runs tests in shell (./test.sh ) |
yes |
make lint | Run golangci lint checks | yes |
make lint-fix | Run golangci to automatically perform fixes | no |
make test-coverage | Run coveralls to check the % of code covered by tests | yes |
make check-testdata | Checks if the testdata dir is updated with the latest changes | yes |
make test-e2e-local | Runs the CI e2e tests locally | no |
NOTE To use the make lint
is required to install golangci-lint
locally. More info: https://github.com/golangci/golangci-lint#install
If your intended PR creates a new plugin, make sure the PR also provides test cases. Testing should include:
e2e tests
to validate the behavior of the proposed plugin.sample projects
to verify the scaffolded output from the plugin.
All the plugins provided by Kubebuilder should be validated through e2e-tests
across multiple platforms.
Current Kubebuilder provides the testing framework that includes testing code based on ginkgo, Github Actions for unit tests, and multiple env tests driven by test-infra.
To fully test the proposed plugin:
-
Create a new package(folder) under
test/e2e/<your-plugin>
. -
Create e2e_suite_test.go, which imports the necessary testing framework.
-
Create
generate_test.go
(ref). That should:- Introduce/Receive a
TextContext
instance - Trigger the plugin's bound subcommands. See Init, CreateAPI
- Use PluginUtil to verify the scaffolded outputs. See InsertCode, ReplaceInFile, UncommendCode
- Introduce/Receive a
-
Create
plugin_cluster_test.go
(ref). That should:-
4.1. Setup testing environment, e.g:
- Cleanup environment, create temp dir. See Prepare
- If your test will cover the provided features then, ensure that you install prerequisites CRDs: See InstallCertManager, InstallPrometheusManager
-
4.2. Run the function from
generate_test.go
. -
4.3. Further make sure the scaffolded output works, e.g:
- Execute commands in your
Makefile
. See Make - Temporary load image of the testing controller. See LoadImageToKindCluster
- Call Kubectl to validate running resources. See utils.Kubectl
- Execute commands in your
-
4.4. Delete temporary resources after testing exited, e.g:
- Uninstall prerequisites CRDs: See UninstallPrometheusOperManager
- Delete temp dir. See Destroy
-
-
Add the command in test/e2e/plugin to run your testing code:
go test $(dirname "$0")/<your-plugin-test-folder> $flags -timeout 30m
It is also necessary to test consistency of the proposed plugin across different env and the integration with other plugins.
This is performed by generating sample projects based on the plugins. The CI workflow defined in Github Action would validate the availability and the consistency.
See:
See VERSIONING.md for a full description. TL;DR:
Every PR should be annotated with an icon indicating whether it's a:
- Breaking change:
⚠️ (:warning:
) - Non-breaking feature: ✨ (
:sparkles:
) - Patch fix: 🐛 (
:bug:
) - Docs: 📖 (
:book:
) - Infra/Tests/Other: 🌱 (
:seedling:
) - No release note: 👻 (
:ghost:
)
Use 👻 (no release note) only for the PRs that change or revert unreleased changes, which don't deserve a release note. Please don't abuse it.
You can also use the equivalent emoji directly, since GitHub doesn't
render the :xyz:
aliases in PR titles.
If the PR is "plugin" scoped, you may also append the responding plugin names in the prefix. For instance:
🐛 (kustomize/v2-alpha): Fix typo issue in the labels added to the manifests
Individual commits should not be tagged separately, but will generally be assumed to match the PR. For instance, if you have a bugfix in with a breaking change, it's generally encouraged to submit the bugfix separately, but if you must put them in one PR, mark the commit separately.
- See the action files to check its tests, and the scripts used on it.
- Note that the prow tests used in the CI are configured in kubernetes-sigs/kubebuilder/kubebuilder-presubmits.yaml.
- Check that all scripts used by the CI are defined in the project.
- Notice that our policy to test the project is to run against k8s version N-2. So that the old version should be removed when there is a new k8s version available.
The docs are published off of three branches:
book-v3
: book.kubebuilder.io -- current docsbook-v2
: book-v2.book.kubebuilder.io -- legacy docsbook-v1
: book-v1.book.kubebuilder.io -- legacy docsmaster
: master.book.kubebuilder.io -- "nightly" docs
See VERSIONING.md for more information.
There are certain writing style guidelines for Kubernetes documentation, checkout style guide for more information.
Check the CI job after to do the Pull Request and then, click on in the Details
of netlify/kubebuilder/deploy-preview
Learn how to engage with the Kubernetes community on the community page.
You can reach the maintainers of this project at:
Contributors may eventually become official reviewers or approvers in Kubebuilder and the related repositories. See CONTRIBUTING-ROLES.md for more information.
Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.