So you'd like to contribute? Awesome! Here are some things worth knowing.

Go open an issue and I'll probably reply soon.

If you're willing to contribute your ideas and effort to making the locust-k8s-operator better, then that's awesome and I'm truly grateful. I don't have all the answers and it is important for this project to benefit from diverse perspective and technical expertise.

That being said, please be aware that a lot of thought has gone into the architecture of the project, and whilst I know it's not perfect, and I am very interested in alternative perspectives, I do have opinions (reasonable I hope) about how certain things should. This particularly applies to naming and internal APIs. There is a lot to consider in terms of making sure the tool stays simple, flexible, and performant. So please don't be offended if there is some push back. It is ultimately for the benefit of the tool and nothing more.

When contributing to this repository, please first discuss the change you wish to make via an issue.

Please note that we have a code of conduct and thus you are kindly asked to follow it in all your interactions with the project.

# Build the operator binary
make build

# Run all tests (unit + integration via envtest)
make test

# Run linter
make lint

# Generate CRDs, RBAC, and webhook manifests
make manifests

# Run all CI checks locally
make ci

For local development and testing, Kind (Kubernetes in Docker) is the recommended approach.

• Go 1.26+
• Docker
• Kind
• Helm 3

1. Create a Kind Cluster

   kind create cluster --name locust-dev

2. Build and Load the Docker Image

   Build a Docker image and load it into Kind:

   # Build the Docker image
   make docker-build IMG=locust-k8s-operator:dev
   
   # Load the image into Kind
   kind load docker-image locust-k8s-operator:dev --name locust-dev

3. Install the Operator with Helm

   # Package the Helm chart
   helm package charts/locust-k8s-operator
   
   # Install with local image
   helm install locust-operator locust-k8s-operator-*.tgz \
     --set image.repository=locust-k8s-operator \
     --set image.tag=dev \
     --set image.pullPolicy=IfNotPresent

4. Verify the Deployment

   kubectl get pods -A | grep locust

5. Cleanup

   # Uninstall the operator
   helm uninstall locust-operator
   
   # Delete the Kind cluster
   kind delete cluster --name locust-dev

Across the two PR workflows (ci.yaml and go-test-e2e.yml), the matrix below runs on every PR. If you change cmd/, api/, internal/, or the chart, expect both jobs to fire. lint-test-helm is the one that catches regressions like #317 (operator crashing under the Quick Start install path) via its ci/default-values.yaml scenario — keep it green.

Notes on coverage gaps:

• The Ginkgo e2e suite (test/e2e/) currently runs against the kustomize deploy path only. The Helm install surface is covered by lint-test-helm. Extending the Ginkgo suite to cover Helm is tracked as a follow-up — it requires aligning chart resource names with kustomize conventions used by hardcoded test constants.
• Dedicated helm-default-smoke and helm-upgrade-smoke jobs are tracked as a separate follow-up; they were split out of this PR to land with structural fixes (e.g. replacing the post-rollout-restart restart-count peek with kubectl wait --for=condition=Available).
• Runners are ubuntu-latest (amd64). The published image is multi-arch; arm64-specific regressions are caught only at release time via the release workflow.

All documentation is located under the docs/ directory. The documentation is hosted on gh-pages and updated automatically with each release. To manage and build the documentation, the project uses MkDocs & Material for MkDocs framework to manage and build the documentation.

During development, the CI workflow will build the documentation as part of the validation.

1. Ensure any install or build dependencies are removed before the end layer when doing a build.
2. Update the documentation when needed with the details of the proposed change, this includes any useful information for the end user of the tool maintainer / contributor(s).
3. Make sure that the commit messages are aligned with the used standard. This is very important since the commit message directly influence the content of the CHANGELOG.md and the version increase.
4. Tests
   1. Clean and well written tests are very important.
   2. Changes must not cause any type of regression.
   3. All changes / additions (within reason) must be covered by tests.
   4. If the additions represent a breaking change, existing tests must be updated.