Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
92 lines (65 loc) · 4.59 KB

CONTRIBUTING.md

File metadata and controls

92 lines (65 loc) · 4.59 KB

Contributing

Thanks for taking a look. This template's harness is the product, so the contribution flow is opinionated — every change goes through the same gates as a feature.

Branching

main  ◄── release PR ◄── develop ◄── feat/123-short-name
                                  ◄── fix/124-bug-name
                                  ◄── chore/125-config-change
  • main is the release line. Protected: 21 required status checks, code-owner approval, no force pushes. (One additional non-required check, Draft next release from release-drafter, runs informationally on PRs to main and shows up in the rollup but is not gated.)
  • develop is the integration branch. Same 21 gates, less strict (PRs don't need rebases).
  • Feature branches are short-lived and named <type>/<issue-number>-<kebab-title>. Open one issue per branch so the project board stays usable.

Commit messages

Seven prefixes (enforced in three places — [tool.commitizen] in pyproject.toml, pr-title.yml, check_commit_types.py):

Prefix When
feat: New capability
fix: Bug fix
docs: Documentation only
test: Tests / eval harness
refactor: Internal change with no behaviour delta
chore: Tooling, deps, infra
release: develop → main release PRs only

The subject is lowercase after the colon. Title Case prose (Add the thing) is rejected; all-caps initialisms (CI failure, SDK upgrade) are fine.

Pull requests

  1. Open the issue first. Use a feature/bug template; fill every section.
  2. Branch off develop with the matching name.
  3. If your team uses Beads, mirror or claim the linked issue in the local Beads queue after the issue exists. Beads track local ready/blocked execution only; GitHub Issues remain canonical for scope, discussion, PR linkage, and closure.
  4. Land one logical change per PR. Stack PRs if the work is naturally split.
  5. The PR template asks five things — answer each (None is valid where applicable):
    • What & why (1–3 lines)
    • Test plan (checkbox list; CI covers most of it)
    • Invariants affected — cite numbered rules from docs/INVARIANTS.md
    • New deps / actions / external surface (anchor for supply-chain review)
    • Screenshots (UI changes only)
  6. Wait for green CI + a code-owner review before merging.

Solo-owner merge policy

This repo runs with a single code owner (* @constk in CODEOWNERS). GitHub forbids a PR author from approving their own PR, so the standard "1 code-owner review" gate cannot be satisfied without an admin override. While in this state, the intended workflow is:

gh pr merge <N> --admin --squash --delete-branch

…for feat: / fix: / chore: PRs, and --admin --merge (preserves history) for release: PRs. The enforce_admins: false line in .github/branch-protection/{develop,main}.json is the documented escape hatch — admin merge here is the policy, not a deviation from it.

When a second collaborator joins, drop the --admin flag and adopt standard PR review. Update this section + CODEOWNERS in the same PR.

Local pre-push gate

just check                     # ruff + mypy + import-linter + pytest
cd frontend && npm run lint && npm run format:check && npm run check && npm run test && npm run build
uv run pre-commit run --all-files

A green pre-push run is a high-confidence predictor of a green CI run. The just check gate is intentionally a subset of CI — fast feedback over coverage.

Adding a check

When the harness grows a new gate:

  1. Add the workflow job in .github/workflows/.
  2. If it's a required gate, add the job's display name to the contexts arrays in .github/branch-protection/{develop,main}.json.
  3. If it's NOT required (scheduled / dispatch-only / push-to-main-only), add the workflow filename to EXEMPT_WORKFLOWS in .github/scripts/check_required_contexts.py.
  4. Update docs/HARNESS.md and docs/SECURITY.md (if security-relevant).
  5. Land in one PR — the meta-gate Branch-protection contexts sync will fail if you skip step 2 or 3.

Code of conduct

Be kind. Disagree on substance, not on people. If review feedback gets sharp, take it offline and come back when both sides are ready.

Reporting security issues

If you find a vulnerability that affects users of the template, do not open a public issue. Email the maintainer (see commit history for contact). Include:

  • Repro steps
  • Affected version / commit SHA
  • Severity assessment (informational / low / medium / high / critical)
  • Suggested fix if you have one

We'll acknowledge within 72 hours.