Your First Contribution

Your First Contribution

You do not need a Kubernetes cluster, an LLM API key, or Docker to contribute. The test suites are fully mocked. You need Python 3.12+ and about five minutes.

---

1. Set up (one command)

git clone https://github.com/MSKazemi/kubeintellect.git
cd kubeintellect
make setup

This installs uv if you don't have it, installs the whole v4 workspace, then runs six of the nine checks required to merge, so you know your environment is correct before you change anything:

Gate	Command
Lint	uv run ruff check packages/kubeintellect-server/app/ packages/ki-protocol/
Types	uv run mypy packages/kubeintellect-server/app packages/ki-protocol packages/kube-q/kube_q
Server tests	uv run python -m pytest tests/ -q
CLI tests	cd packages/kube-q && uv run python -m pytest tests/ -q
File modes	make check-modes (repo root)
Syntax warnings	make check-syntax (repo root)

If it ends with "You are ready to contribute", you are done setting up.

Three more checks run only in CI, because they need a clean machine or a second interpreter: Install smoke test, Tests (server · py3.13) and Tests (kube-q CLI · py3.13). A green make setup therefore does not guarantee a green PR — if one of those three is red on its own, it is a real failure worth reading.

If any gate fails on a clean checkout, that is our bug, not yours — please tell us.

Zero-install alternative: open a Codespace — the devcontainer runs the same setup for you.

2. Pick something

• github.com/MSKazemi/kubeintellect/contribute — the curated first-issue list
• good first issue — each one names the file, the line, and the command that proves you fixed it
• help wanted — larger, still scoped

Comment "I'd like to take this" on the issue. No permission needed, and nobody will take it out from under you.

Not code? These count, and they are genuinely useful:

• Add your environment to #51 — even "Kind on my laptop". Listed environments are the ones that get tested against.
• 👍 the items in #52 — reaction counts are the project's only prioritisation signal, and they really do reorder the roadmap.
• Fix anything on this wiki that misled you.
• Answer someone in Q&A.

3. Know where you are

v4/ is the only tree that takes behavioural changes.

Path	Changes
v4/	✅ active development
v3/, v2/	🔸 bug fixes and docs only
v1/	❄️ frozen — it is the architecture in the published paper

The older trees are deliberately independent snapshots of a design lineage. Please don't de-duplicate across them.

4. Make the change

Two expectations, both non-negotiable, both simple:

1. A test that fails before your change and passes after. Write the test first, run it against the unpatched code, watch it fail. If it can't fail, it isn't testing anything.
2. If you touch a command that emits a diagnosis, report or summary, run it by hand against a deliberately absent resource — a made-up session id, no cluster. It must refuse, not return something plausible. This is the one output shape the project cannot ship, and CI cannot catch it.

Using an AI assistant is welcome — just say so in the PR. It tells reviewers where to look, nothing more. AGENTS.md in the repo root gives your agent the build/test/lint rules and the safety invariants.

5. Commit and open the PR

Sign-off is required (DCO):

git commit -s -m "fix(packaging): point kube-q's project URLs at the canonical repository"
git push -u origin my-branch
gh pr create --fill --body "Closes #74"

Forgot the -s? git commit --amend -s fixes it.

6. What happens next

• Your PR will show no CI checks and a blocked merge box. That is expected on a fork PR from a first-time contributor — GitHub runs nothing until a maintainer approves the run. It is not your fault and needs no action from you.
• Every issue and PR gets a human first response — even when the answer is "not this way", it arrives rather than silence (TRIAGE.md). There is deliberately no time commitment attached: one person maintains this, and a number that gets missed is worse than no number. In practice it is usually within a week. If your thread goes quiet, a nudge is welcome rather than rude.
• Pre-existing ruff format debt failing is not your bug — say so in the PR.
• Contributors are credited in CHANGELOG.md and the release notes.

---

Got stuck at any step above? That is a documentation defect. Saying so in Q&A is itself a contribution, and this page gets fixed.