orca-platform/CONTRIBUTING.md

Contributing

Conventions are platform-wide. The full ruleset lives in platform/docs/IMPLEMENTATION_PLAN.md §1. This is the short version.

Branching

• Trunk-based. main is always deployable.
• Branch from main. Name: feat/<slug>, fix/<slug>, chore/<slug>, docs/<slug>, refactor/<slug>.
• Max 5 days. Longer-lived branches get merge conflicts and stop being trusted.
• Never push directly to main (branch protection blocks it).

Commits

Conventional Commits — enforced by commitlint in CI.

<type>(<scope>)?: <subject>

[optional body]

[optional footer: BREAKING CHANGE: ..., Refs: M5.2]

Types: feat, fix, chore, docs, refactor, test, perf, build, ci. Breaking change: append ! (e.g. feat!: drop /v0 endpoints) and add BREAKING CHANGE: footer.

Examples:

feat(api): add POST /v1/tenants/:id/cancel
fix(auth): reject JWT when org_id missing
docs: link runbook from README
refactor!: rename column tenant.kind → tenant.type

Pull requests

1. Open a PR against main using the template (.gitea/pull_request_template.md is auto-loaded).
2. Fill every section — the template is a checklist, not decoration.
3. Link the milestone in the body: Linked milestone: M5.2.
4. Wait for green CI + 1 approving review. Do not self-merge.
5. Squash-merge. The PR title becomes the commit message — keep it as a Conventional Commit.

Tests

Change type	Required tests
New API endpoint	unit + integration (testcontainers, real DB)
New user-facing flow	Playwright e2e against stage
Bug fix	regression test FIRST (must fail before fix)
IaC / Orca manifest	orca validate + dry-run plan in PR comment
Pure refactor	existing suite must stay green

"Manually tested" is not acceptable except for IaC, and even there the dry-run plan must be in the PR.

Secrets

• Never commit secrets. gitleaks runs in CI and blocks merge.
• Local dev: .env.local (gitignored); template at .env.example.
• Stage / prod: Infisical machine identity at /{env}/{service}/.

Code style

Stack	Tools
Go	go fmt, go vet, golangci-lint run — all required clean
Rust	cargo fmt --all, cargo clippy -- -D warnings — both required
TypeScript	pnpm lint, pnpm typecheck — both required
Python	ruff check, ruff format, mypy — all required

CI runs these. Pre-commit hooks recommended (.githooks/pre-commit in this repo).

Audit + observability

Any state-changing endpoint MUST emit an audit event to Tenant Registry /audit in the Retraced-shape schema. See PRODUCT_INTEGRATION_SPEC.md §8.4.

Any service ships OTel SDK from day one (OTEL_EXPORTER_OTLP_ENDPOINT injected by Orca). No fmt.Println / console.log in committed code.

Reviewer hat

When reviewing, check in this order:

1. Risk — what could break in prod? Is the rollback clear?
2. Tests — do they actually exercise the change?
3. Security — secrets, authz, input validation, tenant scoping.
4. Correctness — does it do what the PR says it does?
5. Style — last; CI already caught the mechanical stuff.

Questions

#engineering channel · oncall@breakpilot.com · or open a PR with a [WIP] prefix and ask in the description.