From cab17e02305278bef5e40c73bc610ca9f4ba9256 Mon Sep 17 00:00:00 2001 From: Scrubs McBarkley Date: Thu, 16 Apr 2026 10:39:40 +0000 Subject: [PATCH 1/2] docs: add CONTRIBUTING.md with branch strategy Document the three-branch GitOps model (dev/uat/main), developer workflow, promotion flow, and branch protection rules. Refs GRO-702 Co-Authored-By: Paperclip --- CONTRIBUTING.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8dd1af6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,84 @@ +# Contributing to GroomBook + +## Branch Strategy + +GroomBook uses a three-branch GitOps model: + +| Branch | Environment | Purpose | +|--------|-------------|---------| +| `dev` | Development | Active development target — all feature/fix PRs target this branch | +| `uat` | UAT / Staging | Promoted from `dev` by the CTO for acceptance testing | +| `main` | Production | Promoted from `uat` by the CEO; triggers production deployment | + +**Never open a PR directly to `uat` or `main`.** All work flows through `dev` first. + +## Developer Workflow + +1. **Branch from `dev`** — create a feature or fix branch: + ```bash + git checkout dev + git pull origin dev + git checkout -b feat/my-feature + ``` + +2. **Open a PR targeting `dev`** — include the issue identifier in the title and cc @cpfarhood: + ```bash + gh pr create --base dev --title "feat: description (GRO-NNN)" \ + --body "Closes GRO-NNN\n\ncc @cpfarhood" + ``` + +3. **Pipeline gates before merge to `dev`:** + - QA (Lint Roller) reviews first — code quality, test coverage, CI pass + - CTO (The Dogfather) reviews second — architecture and final approval + - Both must approve; 2 approving reviews required by branch protection + +## Promotion Flow + +### Dev → UAT + +After merging to `dev`, the CTO opens a PR from `dev` → `uat`: + +```bash +gh pr create --base uat --head dev \ + --title "chore: promote dev to uat (YYYY.MM.DD)" \ + --body "Promoting dev to UAT for regression and security review.\n\ncc @cpfarhood" +``` + +Gates: +- Shedward Scissorhands runs regression/acceptance tests +- Barkley Trimsworth performs security review +- CTO approves and merges (1 approving review required) + +### UAT → Main (Production) + +After UAT passes, the CTO assigns the promotion PR to the CEO: + +Gates: +- CEO (Scrubs McBarkley) reviews for business alignment and merges +- 1 approving review required; triggers auto-deploy to Production + +## Branch Protection Summary + +| Branch | Required Approvals | Who approves | +|--------|--------------------|-------------| +| `dev` | 2 | QA (Lint Roller) + CTO (The Dogfather) | +| `uat` | 1 | CTO (The Dogfather) | +| `main` | 1 | CEO (Scrubs McBarkley) | + +Force-pushes and branch deletions are disabled on all three branches. + +## Commit Style + +Use [Conventional Commits](https://www.conventionalcommits.org/): +- `feat:` — new feature +- `fix:` — bug fix +- `chore:` — maintenance (dependency updates, build config, promotions) +- `docs:` — documentation only +- `ci:` — CI/CD changes +- `refactor:` — code restructure without behaviour change + +Reference the Paperclip issue in the commit body: `Refs GRO-NNN`. + +## Questions? + +Open a Paperclip issue in the GRO project or ask in the team channel. From 4a65c30d40e57fdeedec6f1cd6e73d763379709e Mon Sep 17 00:00:00 2001 From: Scrubs McBarkley Date: Thu, 16 Apr 2026 10:43:12 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20fix=20bash=20snippet=20quoting=20an?= =?UTF-8?q?d=20add=20uat=E2=86=92main=20pr=20command?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix \n quoting in two gh pr create commands: use ANSI-C $'...' quoting so newlines render correctly in PR bodies (not literal \n) - Add missing gh pr create example for the UAT → main promotion step Addresses Greptile review feedback on PR #304. Co-Authored-By: Paperclip --- CONTRIBUTING.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8dd1af6..38582cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ GroomBook uses a three-branch GitOps model: 2. **Open a PR targeting `dev`** — include the issue identifier in the title and cc @cpfarhood: ```bash gh pr create --base dev --title "feat: description (GRO-NNN)" \ - --body "Closes GRO-NNN\n\ncc @cpfarhood" + --body $'Closes GRO-NNN\n\ncc @cpfarhood' ``` 3. **Pipeline gates before merge to `dev`:** @@ -41,7 +41,7 @@ After merging to `dev`, the CTO opens a PR from `dev` → `uat`: ```bash gh pr create --base uat --head dev \ --title "chore: promote dev to uat (YYYY.MM.DD)" \ - --body "Promoting dev to UAT for regression and security review.\n\ncc @cpfarhood" + --body $'Promoting dev to UAT for regression and security review.\n\ncc @cpfarhood' ``` Gates: @@ -51,7 +51,13 @@ Gates: ### UAT → Main (Production) -After UAT passes, the CTO assigns the promotion PR to the CEO: +After UAT passes, the CTO opens a PR from `uat` → `main` and assigns it to the CEO: + +```bash +gh pr create --base main --head uat \ + --title "chore: promote uat to main (YYYY.MM.DD)" \ + --body $'Promoting UAT to production.\n\ncc @cpfarhood' +``` Gates: - CEO (Scrubs McBarkley) reviews for business alignment and merges