Skip to content

Git workflow

All change lands through pull requests against main — no direct pushes, including from maintainers. The PR is the unit of review, CI and rollback.

Branches & commits

  • Branch names: feat/…, fix/…, docs/…, chore/…, infra/….
  • Conventional Commits: type(scope): summary, imperative mood; the body explains why when it is not obvious.
  • Branch off current origin/main. When a large PR is unmerged and holds shared state, do not branch new work off main until it lands — check the repo's live-status/handoff notes first to avoid colliding with another session.

Definition of done

A change is complete only with implementation + tests + updated MkDocs pages in the same PR, plus migration/rollback notes where relevant, a security note for any trust-boundary change, and performance numbers for critical paths. Docs and code change together: if the docs don't say it, it isn't operationally true.

Review & merge

  • CI must be green — docs, secrets, markdown, lint, types, tests/coverage.
  • One human approval is required once a repo has a second contributor; CODEOWNERS names the owners. During a genuine solo phase the author may self-merge only when every check is green, and the PR description is the review record (what changed, why, the risk, the rollback).
  • Merges to main affect every session that branches from it — treat them as consequential and coordinate.

Multi-session coordination

Multiple Claude Code / Codex sessions share these repos. Where a durable task queue exists (inva-infrastructure/queue/), claim a task's lease before working it; everywhere else, work on an isolated branch + worktree, record it, and keep the repo's recovery-anchor/handoff note current. See Claude Code usage.