Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
79 lines (57 loc) · 3.44 KB

CONTRIBUTING.md

File metadata and controls

79 lines (57 loc) · 3.44 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: 15 required status checks, code-owner approval, no force pushes.
  • develop is the integration branch. Same 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. Land one logical change per PR. Stack PRs if the work is naturally split.
  4. 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)
  5. Wait for green CI + a code-owner review before merging.

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.