Development workflow

The day-to-day cycle of writing, testing, and submitting a change to kubernetes/kubernetes.

Setting up

Clone via your fork and add upstream as a remote:

git clone https://github.com/<you>/kubernetes
cd kubernetes
git remote add upstream https://github.com/kubernetes/kubernetes
git fetch upstream
git checkout -b my-change upstream/master

Match the Go toolchain in .go-version (currently 1.26.x). The build will reject older versions.

Editing code

The repo is large enough that whole-tree linting and codegen take a while. Scope your work narrowly:

make WHAT=cmd/kubectl              # build a single binary
make test WHAT=./pkg/scheduler/...  # run a single subpackage's unit tests
hack/verify-golangci-lint.sh        # lint the entire tree

Most changes go in either:

• cmd/<binary>/app/ — flag parsing, server bootstrap
• pkg/<subsystem>/ — implementation
• staging/src/k8s.io/<module>/ — published library code (be aware: changes here are mirrored to a separate kubernetes/<module> GitHub repo at release time, so behaviour changes have a wider blast radius)
• test/{integration,e2e,e2e_node}/ — the matching test layer

When to regenerate

Regenerate any time you touch:

• API types in staging/src/k8s.io/api/<group>/<version>/types.go or pkg/apis/<group>/types.go
  • run hack/update-codegen.sh
• Validation, defaulter, or strategy helpers
• CRI proto in staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto
  • run the appropriate hack/update-generated-*.sh script
• Feature gates in pkg/features/kube_features.go or component-base feature lists
  • run hack/update-featuregates.sh
• OpenAPI specs (after type changes)
  • regenerated as part of hack/update-codegen.sh

The umbrella make update runs every regenerator. It's slow but safe.

Commits

• Sign off every commit with git commit -s (DCO line Signed-off-by:).
• Keep one logical change per commit. The reviewers will tell you if you've stuffed too much into one.
• Squash on request. Don't squash preemptively unless asked — review history is easier with intermediate commits.
• Reference issues with Fixes #NNNNN or Updates #NNNNN.

Branching and rebasing

• Always branch from upstream/master.
• Rebase, don't merge. The project enforces a linear history.
• When master moves, git fetch upstream && git rebase upstream/master.
• Resolve conflicts locally, rerun make update if the conflict touched generated code, force-push the branch.

Bot commands

The Prow bot listens for /-prefixed commands in PR comments:

• /test all — re-run failed CI jobs
• /retest — re-run only failures
• /hold — block automatic merge (use it if you need to talk first)
• /unhold — release the hold
• /lgtm, /lgtm cancel — sign off on the change (reviewers)
• /approve, /approve cancel — final approval (approvers from OWNERS)
• /assign @user, /cc @user — pull a specific reviewer in
• /area <area>, /sig <sig>, /kind <kind> — apply triage labels

Cherry-picks

To backport to a release branch:

hack/cherry_pick_pull.sh upstream/release-1.30 <PR-number>

The script creates a fork, opens a PR, and labels it appropriately. Backports must be small, low-risk, and have an approved cherry-pick from a release-team owner.