sharang
5ae9e9db12
ci / shared (pull_request) Successful in 4s
Apply the platform-domain decision (2026-05-18) to every README, workflow, and config in this repo. 3 files updated. Refs: M1.1
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# 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@breakpilot.com` · or open a PR with a `[WIP]` prefix and ask in the description.
|