Contribution Guidelines on Kueue

Coding Guidelines

Mon, 01 Jan 0001 00:00:00 +0000

These guidelines are derived from the existing Kueue codebase. They capture the conventions that make the code consistent, maintainable, and reusable. Follow these when writing new code or reviewing pull requests.

Kueue is a Kubernetes project and follows the upstream Kubernetes conventions. Be familiar with these core guidelines:

SIG Scheduling Contributor Guide — contribution guidance specific to the Kubernetes scheduling ecosystem that Kueue is part of.
Kubernetes Deprecation Policy — rules for API version lifetimes (alpha, beta, GA) and removal timelines.
Kubernetes API Changes — how to evolve API types, add new fields behind feature gates, and handle compatibility across versions.
Kubernetes API Conventions — naming, status conventions, conditions, and general API design patterns.
Feature Gates — the mechanism for staging new features through alpha/beta/GA lifecycles.

Product Code Guidelines

Package Organization

pkg/ contains public-facing library code. Consumers may import these packages.
apis/ holds CRD type definitions organized by group and version (e.g. apis/kueue/v1beta2/).
cmd/ contains executable entry points.
Group utilities by domain under pkg/util/ (e.g. pkg/util/client/, pkg/util/resource/, pkg/util/slices/).

Controller Structure

Controllers follow the controller-runtime reconciler pattern:

Development

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Go (version declared in go.mod)
Docker (required for shell-lint and npm-depcheck)
kubectl
GNU sed (macOS: brew install gnu-sed)

Running lint

Run Go linting across all modules:

Running and debugging tests

Mon, 01 Jan 0001 00:00:00 +0000

Quick start

The most common development workflows:

# Unit tests
make test

# Integration tests
make test-integration

# E2E: build image and run
# Note: PLATFORM=linux/arm64 is only needed on Apple Silicon (arm64).
# On amd64, run: make kind-image-build test-e2e-baseline
PLATFORM=linux/arm64 make kind-image-build test-e2e-baseline

# E2E: build, run, and keep the kind cluster alive between runs
E2E_MODE=dev PLATFORM=linux/arm64 make kind-image-build test-e2e-baseline

Quick filter reference

# Focus on tests matching a name pattern
GINKGO_ARGS="--focus=Scheduler" make test-integration
GINKGO_ARGS="--focus='Creating a Pod requesting TAS'" make test-e2e-baseline

# Filter integration tests by label
INTEGRATION_FILTERS="--label-filter=controller:workload" make test-integration
INTEGRATION_FILTERS="--label-filter=area:jobs" make test-integration

# Filter e2e tests by label
GINKGO_ARGS="--label-filter=feature:jobset" make test-e2e-extended

# Run only a specific integration test directory
INTEGRATION_TARGET='test/integration/singlecluster/scheduler' make test-integration

For the full label taxonomy and more examples, see Running a subset of tests.

Website contributions

Mon, 01 Jan 0001 00:00:00 +0000

The Kueue website (kueue.sigs.k8s.io) is built with Hugo and published through Netlify from the site/ directory.

Local preview

From the repository root:

make site-server

See site/README.md for Hugo version requirements and Netlify parity notes.

Netlify deploy previews

Pull requests that change site/ or netlify.toml receive a Netlify deploy preview. The preview URL follows: