Thanks for your interest in contributing! This document covers the essentials. Whether you're fixing a typo or adding a feature, you're welcome here.
Prerequisites:
- Go 1.25+
- Docker (for building images and running Kind)
- Kind (for local clusters and e2e tests)
make
Clone and build:
git clone https://github.com/projection-operator/projection.git
cd projection
make buildmake build regenerates manifests + DeepCopy code, runs go fmt/go vet,
and produces bin/manager.
Unit and envtest-based integration tests:
make testThis downloads the Kubernetes control-plane binaries for the pinned envtest
version into ./bin/ on first run and produces cover.out.
End-to-end tests (Ginkgo) against a Kind cluster you've already deployed the operator to:
make test-e2eFor debugging a live local cluster, hack/observe.sh is a handy helper
that streams reconciler logs, events, and Projection statuses side by side.
Running a single Go test:
export KUBEBUILDER_ASSETS="$(./bin/setup-envtest use 1.34.1 --bin-dir ./bin -p path)"
go test ./internal/controller/ -run TestName -vHelm chart tests (requires the helm-unittest plugin):
make helm-testmake helm-test auto-installs the plugin on first run.
- Fork the repo and create a branch off
main. - Make your changes. Keep commits focused; squash fixups before opening a PR.
- Use Conventional Commits for
commit messages. Common prefixes:
feat:new user-facing behaviorfix:bug fixdocs:documentation onlychore:tooling, deps, non-functional cleanuptest:test-only changesrefactor:no behavior changeci:CI/workflow changes
- Open a pull request against
main. Fill in the PR template. - A maintainer will review. Squash to logical units before merge.
Before opening a PR, make sure these pass locally:
make lint # golangci-lint
make test # unit + envtestNew behavior should come with tests. If you change CRD fields or RBAC
markers, run make manifests generate (or make build, which chains them).
A couple of gotchas worth knowing before you lose time to them:
kind load docker-imagewith multi-arch manifests on Apple Silicon: Kind's image loader chokes on multi-arch manifest lists with a digest mismatch error. Two workarounds: pull the per-platform tag (:X.Y.Z-arm64) and load that, or skip the load and install the operator with animagePullSecretso the cluster pulls from the registry directly.
Some Kinds carry apiserver-allocated spec fields that must be stripped before mirroring (see limitations.md). The map at internal/controller/projection_controller.go grows case-by-case as users hit gaps. To add an entry:
- Confirm the evidence. There must be a reproducible
spec.FIELD: field is immutable(or equivalent) error when creating the destination against a real apiserver. Defaulted fields re-apply on the destination and do not belong in this map. Speculation is not enough — the cost of a wrong entry is silently dropping user data. - Write the reproducer in the PR body. Include the source object YAML, the Projection YAML, and the apiserver error message. This is what the reviewer verifies against.
- Add the map entry at
internal/controller/projection_controller.go(keep a string-valued path first, for the fuzz seed). - Add a unit subtest in
internal/controller/build_destination_test.gomirroring the existing"strips apiserver-allocated Kind spec fields"cases: populate the source, assert the fields are stripped, assert user-set fields on the same object survive. - Add a fuzz seed in
internal/controller/fuzz_test.go'sFuzzPreserveAPIServerAllocatedFields. - Document — add a row to the limitations.md table and a
### Addedbullet toCHANGELOG.mdunder[Unreleased].
The umbrella issue tracking this work is #32.
This project follows the Contributor Covenant. By participating, you agree to uphold it. Report issues privately via a GitHub Security Advisory.
By contributing, you agree that your contributions will be licensed under the Apache License, Version 2.0, matching the per-file boilerplate already present in the codebase.