K8S Contrib Guidelines

Kubernetes contributor process

Source of truth is the kubernetes/community docs on disk, not memory. Resolve their location first, then read the file before citing it, and cite path#section in every finding.

Step 0 — resolve the docs (do this before citing anything)

COMMUNITY=$("${CLAUDE_PLUGIN_ROOT}/scripts/resolve-community.sh" --data "${CLAUDE_PLUGIN_DATA}")
echo "$COMMUNITY"        # -> <somewhere>/contributors

The script tries, in order:

1. the community_docs_path plugin option, if you set one at enable time;
2. a community/ clone beside your workspace or the current repo, or $GOPATH/src/k8s.io/community;
3. a cached copy under ${CLAUDE_PLUGIN_DATA}/community-docs/, refetched when it is more than 30 days old;
4. a fresh sparse fetch of https://github.com/kubernetes/community into that cache (a few seconds, ~20 MB).

Exit 4 means unresolved. If that happens, do not fall back on remembered conventions — triage verdicts, Prow commands, PR templates and cherry-pick rules all drift, and a confidently-wrong citation is worse than an admitted gap. Say in your output that the guidelines could not be verified, cite the upstream URL instead of a section you did not read, and tell the user how to fix it (the script prints the three options).

Whatever resolves, it is a snapshot. If a claim matters and the copy looks stale relative to upstream, prefer the copy on disk — it is what the user reads — and note the drift explicitly.

All paths below are relative to the resolved $COMMUNITY directory.

Where things are

Upstream mirrors, for drift checks only: https://github.com/kubernetes/community/tree/main/contributors/devel and https://www.kubernetes.dev/docs/guide/issue-triage/.

Issue triage — the decision the user is asked to approve

From guide/issue-triage.md. New issues get needs-triage automatically; /triage accepted removes it and adds triage/accepted.

Priorities: priority/critical-urgent (drop everything: user-visible bugs in core features, broken builds, critical security), priority/important-soon, priority/important-longterm, priority/backlog, priority/awaiting-more-evidence.

Staleness: 90 days of inactivity → lifecycle/stale from the triage robot; /remove-lifecycle stale clears it, /lifecycle frozen prevents it.

No response within 20 days on a needs-information issue → close with a comment.

Support channels: https://kubernetes.io/docs/home/, https://discuss.kubernetes.io, https://kubernetes.slack.com.

This system drafts Prow comments. It never posts them. Every /triage, /close, /sig, /kind, /lgtm, /approve, /retest is a draft in issue-comment.md for the user to send. A PreToolUse hook blocks any command carrying a Prow slash-command.

Coding conventions

From guide/coding-conventions.md — read it, it is only ~60 lines.

• Go: Go Code Review Comments, Effective Go, avoid the known Go landmines.
• Naming: consider the package name and avoid redundancy — storage.Interface, not storage.StorageInterface. No uppercase, underscores, or dashes in package names. pkg/controllers/autoscaler/foo.go is package autoscaler, not package autoscalercontroller. The package line should match its directory unless there is a good reason.
• Locks are called lock and are never embedded: lock sync.Mutex. With several, name each: stateLock, mapLock.
• Command-line flags use dashes, not underscores.
• Comment your code; if a reviewer asks why it is the way it is, that is a sign a comment was missing.
• All filenames lowercase. Go files and dirs use underscores; doc files use dashes.
• Avoid package sprawl and "util" packages — name the function's domain (wait.Poll, not util.Poll).

Testing conventions

• All new packages and most new significant functionality need unit tests.
• Table-driven tests are preferred for multiple scenarios/inputs.
• Significant features need integration (test/integration) and/or e2e (test/e2e) tests — including new kubectl commands.
• Unit tests must pass on macOS and Windows. Linux-specific tests must be skipped on Windows (preferred when running Linux-only commands) or compiled out (required when the code will not build on Windows).
• Do not expect an asynchronous thing to happen immediately. Never sleep a second and assert a pod is running — wait and retry.
• Avoid Docker Hub; use the Google Cloud Artifact Registry.
• Integration tests should only touch local resources (etcd, localhost services). Each test creates its own server and config.

Integration test invocation (devel/sig-testing/integration-tests.md):

hack/install-etcd.sh                          # installs into ./third_party/etcd
export PATH=$PATH:$(pwd)/third_party/etcd
make test-integration WHAT=./test/integration/pods GOFLAGS="-v" \
     KUBE_TEST_ARGS="-run ^TestPodUpdateActiveDeadlineSeconds$"

TEST_ETCD_DIR overrides where internally started etcd instances write data.

Pull requests

Read the repo's actual PR template — do not reproduce one from memory. For kubernetes/kubernetes it is .github/PULL_REQUEST_TEMPLATE.md, whose current sections are:

• #### What type of PR is this? — /kind bug, plus optional /kind api-change, /kind deprecation, /kind failing-test, /kind flake, /kind regression
• #### What this PR does / why we need it:
• #### Which issue(s) this PR is related to: — Fixes #<n>. Do not use "Fixes" when the PR is kind/failing-test or kind/flake.
• #### Special notes for your reviewer:
• #### Does this PR introduce a user-facing change? — a ```release-note fenced block, or NONE
• #### Additional documentation … — a ```docs fenced block

Then /sig <sig> and /cc @<owners> lines.

More detail: references/pr-and-review.md.

Cherry-picks

From devel/sig-release/cherry-picks.md. Only these are backported:

• security fixes (but not dependency bumps that merely silence a scanner)
• regression fixes (not if the regression only occurs with an off-by-default alpha feature enabled)
• critical bug fixes: data loss, memory corruption, panic, crash, hang (same alpha-feature exclusion)
• prerequisites for critical dependency updates
• test-only changes that stabilize failing/flaky tests on release branches

Cherry-pick to every supported release branch, newest first, via hack/cherry_pick_pull.sh upstream/release-X.Y <PR>. Explain any branch you skip.

More references

• references/pr-and-review.md — PR template, review expectations, release notes, OWNERS
• references/testing-tiers.md — which tier proves what, and the flake policy
• references/api-and-compat.md — API changes, feature gates, version skew, logging and metrics conventions