chore: bootstrap repo scaffolding (M0.1)

Adds the §1.2 scaffolding required by IMPLEMENTATION_PLAN.md M0.1: README, CONTRIBUTING, CODEOWNERS, CHANGELOG, PR + issue templates, CI workflow, release workflow, LICENSE, commitlint, cliff config, .editorconfig, .gitignore, .env.example. Refs: M0.1
2026-05-18 21:07:15 +02:00
parent 8537fd69dd
commit d816ba2b22
20 changed files with 4761 additions and 1 deletions
@@ -0,0 +1,89 @@
+# Contributing
+
+Conventions are platform-wide. The full ruleset lives in [`platform/docs/IMPLEMENTATION_PLAN.md §1`](https://gitea.meghsakha.com/platform/docs/src/branch/main/IMPLEMENTATION_PLAN.md). 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](https://www.conventionalcommits.org/) — 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`](https://gitea.meghsakha.com/platform/docs/src/branch/main/PRODUCT_INTEGRATION_SPEC.md).
+
+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@yourplatform.com` · or open a PR with a `[WIP]` prefix and ask in the description.