groombook/app
Archived
13
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add CONTRIBUTING.md with branch strategy (GRO-702) #304

Merged
scrubs-mcbarkley-ceo[bot] merged 2 commits from docs/branch-strategy-contributing into dev 2026-04-16 10:59:16 +00:00
Conversation 4 Commits 2 Files Changed 1
+90
1 changed files with 90 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+90
View File
@@ -0,0 +1,90 @@
# 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'
```
greptile-apps[bot] commented 2026-04-16 10:41:46 +00:00 (Migrated from github.com)
Review
Copy Link
Copy Source

P1 \n in double-quoted strings won't produce newlines

In bash, \n inside double quotes ("...") is not interpreted as a newline — it is passed to gh as a literal backslash-n, resulting in a PR body like Closes GRO-NNN\n\ncc @cpfarhood rather than the intended multi-line text. The same issue appears on line 43–44 in the Dev → UAT promotion command.

Use ANSI-C quoting ($'...') so the shell interprets \n before passing the value to gh:

  --body $'Closes GRO-NNN\n\ncc @cpfarhood'

Or the equivalent using printf:

--body "$(printf 'Closes GRO-NNN\n\ncc @cpfarhood')"
Prompt To Fix With AI 
This is a comment left during a code review.
Path: CONTRIBUTING.md
Line: 26-28

Comment:
**`\n` in double-quoted strings won't produce newlines**

In bash, `\n` inside double quotes (`"..."`) is **not** interpreted as a newline — it is passed to `gh` as a literal backslash-n, resulting in a PR body like `Closes GRO-NNN\n\ncc @cpfarhood` rather than the intended multi-line text. The same issue appears on line 43–44 in the Dev → UAT promotion command.

Use ANSI-C quoting (`$'...'`) so the shell interprets `\n` before passing the value to `gh`:

```suggestion
  --body $'Closes GRO-NNN\n\ncc @cpfarhood'
```

Or the equivalent using `printf`:
```bash
--body "$(printf 'Closes GRO-NNN\n\ncc @cpfarhood')"
```

How can I resolve this? If you propose a fix, please make it concise.
<a href="#"><img alt="P1" src="https://greptile-static-assets.s3.amazonaws.com/badges/p1.svg?v=7" align="top"></a> **`\n` in double-quoted strings won't produce newlines** In bash, `\n` inside double quotes (`"..."`) is **not** interpreted as a newline — it is passed to `gh` as a literal backslash-n, resulting in a PR body like `Closes GRO-NNN\n\ncc @cpfarhood` rather than the intended multi-line text. The same issue appears on line 43–44 in the Dev → UAT promotion command. Use ANSI-C quoting (`$'...'`) so the shell interprets `\n` before passing the value to `gh`: ```suggestion --body $'Closes GRO-NNN\n\ncc @cpfarhood' ``` Or the equivalent using `printf`: ```bash --body "$(printf 'Closes GRO-NNN\n\ncc @cpfarhood')" ``` <details><summary>Prompt To Fix With AI</summary> `````markdown This is a comment left during a code review. Path: CONTRIBUTING.md Line: 26-28 Comment: **`\n` in double-quoted strings won't produce newlines** In bash, `\n` inside double quotes (`"..."`) is **not** interpreted as a newline — it is passed to `gh` as a literal backslash-n, resulting in a PR body like `Closes GRO-NNN\n\ncc @cpfarhood` rather than the intended multi-line text. The same issue appears on line 43–44 in the Dev → UAT promotion command. Use ANSI-C quoting (`$'...'`) so the shell interprets `\n` before passing the value to `gh`: ```suggestion --body $'Closes GRO-NNN\n\ncc @cpfarhood' ``` Or the equivalent using `printf`: ```bash --body "$(printf 'Closes GRO-NNN\n\ncc @cpfarhood')" ``` How can I resolve this? If you propose a fix, please make it concise. ````` </details>
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'
```
greptile-apps[bot] commented 2026-04-16 10:41:47 +00:00 (Migrated from github.com)
Review
Copy Link
Copy Source

P1 Same \n newline issue in promotion command

Same as the Dev workflow command — \n inside double quotes is a literal backslash-n in bash, not a newline. Fix with ANSI-C quoting:

  --body $'Promoting dev to UAT for regression and security review.\n\ncc @cpfarhood'
Prompt To Fix With AI 
This is a comment left during a code review.
Path: CONTRIBUTING.md
Line: 43-45

Comment:
**Same `\n` newline issue in promotion command**

Same as the Dev workflow command — `\n` inside double quotes is a literal backslash-n in bash, not a newline. Fix with ANSI-C quoting:

```suggestion
  --body $'Promoting dev to UAT for regression and security review.\n\ncc @cpfarhood'
```

How can I resolve this? If you propose a fix, please make it concise.
<a href="#"><img alt="P1" src="https://greptile-static-assets.s3.amazonaws.com/badges/p1.svg?v=7" align="top"></a> **Same `\n` newline issue in promotion command** Same as the Dev workflow command — `\n` inside double quotes is a literal backslash-n in bash, not a newline. Fix with ANSI-C quoting: ```suggestion --body $'Promoting dev to UAT for regression and security review.\n\ncc @cpfarhood' ``` <details><summary>Prompt To Fix With AI</summary> `````markdown This is a comment left during a code review. Path: CONTRIBUTING.md Line: 43-45 Comment: **Same `\n` newline issue in promotion command** Same as the Dev workflow command — `\n` inside double quotes is a literal backslash-n in bash, not a newline. Fix with ANSI-C quoting: ```suggestion --body $'Promoting dev to UAT for regression and security review.\n\ncc @cpfarhood' ``` How can I resolve this? If you propose a fix, please make it concise. ````` </details>
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 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
- 1 approving review required; triggers auto-deploy to Production
greptile-apps[bot] commented 2026-04-16 10:41:48 +00:00 (Migrated from github.com)
Review
Copy Link
Copy Source

P2 Missing gh pr create command for UAT → Main

The Dev → UAT section includes a full copy-paste gh pr create snippet, but the UAT → Main section only describes what the CTO does without providing the equivalent command. For consistency and discoverability, consider adding the corresponding snippet, e.g.:

gh pr create --base main --head uat \
  --title "chore: promote uat to main (YYYY.MM.DD)" \
  --body $'Promoting UAT to production.\n\ncc @cpfarhood'

This helps the CTO follow the same self-documenting pattern.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: CONTRIBUTING.md
Line: 52-58

Comment:
**Missing `gh pr create` command for UAT → Main**

The Dev → UAT section includes a full copy-paste `gh pr create` snippet, but the UAT → Main section only describes what the CTO does without providing the equivalent command. For consistency and discoverability, consider adding the corresponding snippet, e.g.:

```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'
```

This helps the CTO follow the same self-documenting pattern.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

<a href="#"><img alt="P2" src="https://greptile-static-assets.s3.amazonaws.com/badges/p2.svg?v=7" align="top"></a> **Missing `gh pr create` command for UAT → Main** The Dev → UAT section includes a full copy-paste `gh pr create` snippet, but the UAT → Main section only describes what the CTO does without providing the equivalent command. For consistency and discoverability, consider adding the corresponding snippet, e.g.: ```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' ``` This helps the CTO follow the same self-documenting pattern. <details><summary>Prompt To Fix With AI</summary> `````markdown This is a comment left during a code review. Path: CONTRIBUTING.md Line: 52-58 Comment: **Missing `gh pr create` command for UAT → Main** The Dev → UAT section includes a full copy-paste `gh pr create` snippet, but the UAT → Main section only describes what the CTO does without providing the equivalent command. For consistency and discoverability, consider adding the corresponding snippet, e.g.: ```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' ``` This helps the CTO follow the same self-documenting pattern. How can I resolve this? If you propose a fix, please make it concise. ````` </details> Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
## 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.