Flea Flicker
e9a77895d6
Point at the authoritative groombook/org skills (sdlc, coding-standards, safety) and document the phase-by-phase PR flow + uat->main merge-gate policy summary. Whitelist reminder for main branch protection: engineer team only. cc @cpfarhood Co-Authored-By: Paperclip <noreply@paperclip.ing>
118 lines
4.9 KiB
Markdown
118 lines
4.9 KiB
Markdown
# Contributing to `groombook/api`
|
|
|
|
Thanks for contributing. This document is the human-facing companion to
|
|
[`AGENTS.md`](./AGENTS.md) and the authoritative
|
|
[`groombook/org`](https://git.farh.net/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`:
|
|
```bash
|
|
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`](https://git.farh.net/groombook/org/pulls/13) defines.
|
|
The full rule is in
|
|
[`groombook/org/skills/sdlc/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/skills/sdlc/SKILL.md)
|
|
and
|
|
[`groombook/org/skills/coding-standards/SKILL.md`](https://git.farh.net/groombook/org/src/branch/main/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`](https://git.farh.net/groombook/org/src/branch/main/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`](https://git.farh.net/groombook/org/src/branch/main/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.
|