api/CONTRIBUTING.md

Contributing to groombook/api

Thanks for contributing. This document is the human-facing companion to AGENTS.md and the authoritative groombook/org skills. The org skills govern; this file is a quick-reference for the human/agent PR flow in this repo.

Branch strategy

Three long-lived branches; one PR per promotion step.

Branch	Environment	Who merges	Prerequisites for merge
dev	Dev	Engineer	CI passes
uat	UAT	Engineer	QA code review approval
main	Production	Engineer	UAT validation + CTO Gitea Approve when the uat→main merge-gate policy applies (see below)

Engineers always target dev first. Feature branches: <agent-name>/<short-description>.

Phase-by-phase PR flow

Phase 1 — Dev

1. Branch from dev: git checkout -b <name>/<short-description> origin/dev.
2. Write code + tests. Run unit tests, type check, and lint locally (or rely on CI).
3. Open a PR against dev:

   tea pr create --base dev --title "..." --body "..."
   

   Include cc @cpfarhood at the bottom of the body for board visibility.
4. CI must pass. CI green → engineer self-merges.
5. CI builds and deploys to Dev automatically.

Phase 2 — UAT promotion

1. Open a PR from dev to uat.
2. CI must pass.
3. QA (Lint Roller) reviews and approves on the Gitea PR.
4. QA approved → engineer self-merges.
5. CI builds and deploys to UAT automatically.

Phase 3 — UAT regression + Security review

1. UAT (Shedward Scissorhands) runs full regression against UAT — every feature, old and new, no exceptions.
2. Security (Barkley Trimsworth) reviews the changes.
3. Failures in either gate bounce back to Phase 1.

Phase 4 — Production promotion (uat → main)

This is the gate the org PR groombook/org#13 defines. The full rule is in groombook/org/skills/sdlc/SKILL.md and groombook/org/skills/coding-standards/SKILL.md; the summary is below.

The CTO Gitea Approve click is NOT the default gate. Once the four pre-gates (QA, UAT deploy, UAT regression, security) are green, the engineer self-merges.

A CTO Gitea Approve click IS required only for PRs in one of three categories:

1. Novel auth / session paths — login, OIDC, OOBE, session middleware, token issuance, password reset, MFA, new auth provider integrations. Routine auth-gated UI (button styling, error messages, form layout) is not in this category.
2. Infra / prod-affecting merges — deploys, infra manifests, secrets, GitOps overlays, CI/CD, main branch protection, production routing/ingress, prod state mutations. All Phase 5 infra overlay PRs in groombook/infra require CTO Gitea Approve without exception.
3. Risk-flagged merges — risk:cto-approve label, or explicit CTO/CEO sign-off request in the PR or issue thread.

The engineer opens the uat→main PR, classifies it against the three categories above, and adds cc @cpfarhood. If the PR is in scope, the CTO clicks Approve; once approved (and the four pre-gates are green), the engineer merges.

Phase 5 — Production deployment

A separate PR in groombook/infra bumps the overlay image tag for prod. Handed to QA (Lint Roller) for review, then self-merged by the engineer.

The four pre-gates (uat→main)

A uat→main PR is mergeable when all four are green:

1. QA code review — done on the dev→uat promotion PR.
2. UAT deploy — the UAT image built from the uat tip is live in UAT.
3. UAT regression — Shedward's full-feature UAT pass is green (no pre-existing defects, no new defects).
4. Security review — Barkley's security code review is green.

Issue-thread QA / UAT / security approvals do not clear the Gitea required_approvals gate. Only a Gitea Approve click from a member of the approvals_whitelist_username for main clears it. In this repo that whitelist is the engineer team (gb_flea, gb_dogfather).

Style, tests, and quality bar

See groombook/org/skills/coding-standards/SKILL.md for the engineering priority ordering, test requirements, no-hardcoded-values rules, CalVer versioning policy, and the git.farh.net container registry policy.

Safety

See groombook/org/skills/safety/SKILL.md for the non-negotiable rules: no plaintext secrets, no kubectl apply to groombook, no self-merge, no direct tofu runs, board approval for destructive actions, escalation protocol.