Contributing to Kelos

Thank you for helping improve Kelos. Contributions can include bug fixes, features, tests, documentation, examples, and issue reports.

Before You Start

• Search existing issues before opening a new one.
• For a significant change, open an issue first so the approach and API can be discussed before implementation.
• Keep each change focused. Avoid unrelated refactoring in the same pull request.

Development Setup

You need:

• Git
• The Go version declared in go.mod
• Make
• Docker only when building container images
• A Kubernetes cluster and agent credentials only when running end-to-end tests

Fork the repository, clone your fork, and create a branch from the latest main:

git clone https://github.com/<your-user>/kelos.git
cd kelos
git remote add upstream https://github.com/kelos-dev/kelos.git
git fetch upstream
git switch -c <branch-name> upstream/main

The Makefile installs its development tools into bin/ as needed.

Build and Test

Use the repository's Make targets for development and CI checks:

Command	Purpose
make update	Regenerate code, CRDs, and manifests; format Go, YAML, and shell files; and tidy Go modules
make verify	Check generated files, formatting, Go modules, and go vet without retaining generated changes
make test	Run unit tests
make test-integration	Run integration tests with envtest
make build	Build the binaries into bin/
make test-e2e	Run end-to-end tests against a configured cluster

Run make update after changing Go APIs, dependencies, YAML, or shell scripts, and commit any resulting files. Do not edit generated files directly. For code changes, run the standard local checks before submitting a pull request:

make update
make verify
make test
make test-integration
make build

For documentation-only changes, make verify is sufficient. If an integration test is not relevant to your change or cannot run in your environment, explain that in the pull request.

End-to-end tests require a Kubernetes cluster and agent credentials. Run them when your environment is configured for them; otherwise, describe the tests you ran in the pull request.

Making Changes

• Follow the style and patterns in the surrounding code.
• Add or improve tests for behavior you change. Cover the successful path as well as relevant error paths.
• Keep log messages capitalized and without trailing punctuation.
• Include the resource name in CLI errors about a named resource.
• Update documentation and examples when behavior, configuration, or project structure changes. Document only behavior that is implemented.
• Do not put secret environment variable values into Go flag defaults, because defaults are printed in help output.
• Compare Kubernetes resource.Quantity values with their semantic Equal or Cmp methods rather than structural equality.

Kubernetes API Changes

Kubernetes APIs are compatibility contracts and require extra care:

• Add new capabilities only to the latest served/storage API version (currently api/v1alpha2). Keep older versions as compatibility surfaces.
• Preserve compatibility with existing manifests. Do not change an existing field's kind or add validation that rejects values previously accepted.
• Deprecate and retain a replaced field instead of removing it.
• Keep new API surfaces to the minimum needed for the current change.
• Update conversion logic and tests when necessary.
• Run make update and commit all generated CRDs, clients, and manifests.
• Update affected files under examples/, self-development/, and docs/.

Commits and Pull Requests

Write clear commit messages and do not include pull request links in commit messages. Rebase onto the latest upstream/main before submitting when needed; do not add merge commits to your branch.

Every pull request must follow the pull request template:

• Fill in every section; use N/A where appropriate.
• Choose exactly one kind: /kind api, /kind bug, /kind cleanup, /kind docs, or /kind feature. Use /kind api for pull requests that modify files under api/.
• Link the associated issue, or write N/A if there is none.
• Add a meaningful release note for a user-facing change. Write NONE in the release-note block when there is no user-facing change.
• Explain what changed, why it is needed, and how it was tested.
• Keep generated files, tests, examples, and documentation in the same pull request as the change that requires them.

Squash Commits

After review and before merge, clean up the branch so every remaining commit is a meaningful milestone or logical unit of work. Squash commits that only contain review fixes, typo corrections, work in progress, merges, or rebases. A pull request containing one logical change should usually end with one commit.

Use an interactive rebase to combine commits, then safely update your remote branch:

git fetch upstream
git rebase -i upstream/main
git push --force-with-lease

In the interactive rebase, leave pick on commits that should remain and use squash or fixup on follow-up commits that belong with the preceding commit. Use --force-with-lease, not --force, so the push fails rather than overwriting remote work you do not have locally. For more detail, see the Kubernetes contributor guide to squashing commits.

CI runs the build, verification, unit, integration, and applicable end-to-end checks. Please address failures and reviewer feedback with focused follow-up commits.

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.