| 1 | # Branch and Generated-Data PR Hygiene |
| 2 | |
| 3 | Guidelines for keeping branches, PRs, and generated-data syncs clean and reviewable. |
| 4 | |
| 5 | ## Principles |
| 6 | |
| 7 | 1. **Separation of concerns** — product/code PRs, generated-data sync PRs, and platform/infra PRs must remain separate. Never bundle unrelated changes. |
| 8 | 2. **Clean worktrees** — PRD moves, generated-data syncs, and platform upgrades must start from a clean worktree (`git status` shows nothing untracked or modified). |
| 9 | 3. **Focused commits** — each commit should address one logical change. Squash fixups before requesting review. |
| 10 | |
| 11 | ## Generated-Data Sync PRs |
| 12 | |
| 13 | Generated-data PRs (e.g., weekly crawl artifacts in `data/`) follow these rules: |
| 14 | |
| 15 | - **Isolation:** generated-data sync PRs contain only data files and their corresponding metadata (manifests, checksums). No source code, template, or documentation changes. |
| 16 | - **Branch naming:** use `data/sync-{date}` or `data/{descriptive-slug}` (e.g., `data/sync-2026-w24`). |
| 17 | - **Review scope:** reviewers verify the data pipeline ran correctly and output is well-formed — they do not need to re-review the pipeline code itself. |
| 18 | - **Example:** PR #326 demonstrates the pattern — generated-data sync isolated from product changes. |
| 19 | |
| 20 | ## Product / Code PRs |
| 21 | |
| 22 | - **Branch naming:** use `feat/`, `fix/`, `docs/`, `squad/` prefixes as appropriate. |
| 23 | - **Scope:** one feature, bug fix, or docs change per PR. If a change touches multiple concerns, split it. |
| 24 | - **Dependencies:** if a code PR depends on a data sync landing first, note this in the PR description. |
| 25 | |
| 26 | ## Stacked PRs |
| 27 | |
| 28 | Stacked PRs (where PR B targets PR A's branch) are acceptable when: |
| 29 | |
| 30 | - Changes are sequential and tightly coupled (e.g., schema migration followed by code using new schema). |
| 31 | - Each PR is independently reviewable and testable at its layer. |
| 32 | |
| 33 | When using stacked PRs: |
| 34 | |
| 35 | - Note the base branch and merge order in each PR description. |
| 36 | - After the base PR merges, retarget dependent PRs to `main`. |
| 37 | - Never merge a dependent PR before its base PR. |
| 38 | |
| 39 | ## Dirty Worktree Policy |
| 40 | |
| 41 | **Never commit from a dirty worktree** for: |
| 42 | |
| 43 | - PRD/doc moves to `docs/processed/` |
| 44 | - Generated-data sync PRs |
| 45 | - Platform upgrades or dependency bumps |
| 46 | - Squad configuration changes |
| 47 | |
| 48 | If unrelated modified/untracked files exist, stash or resolve them before creating the PR branch. |
| 49 | |
| 50 | ## Reviewer Checklist |
| 51 | |
| 52 | Before approving any hygiene-sensitive PR, verify: |
| 53 | |
| 54 | - [ ] PR contains only changes described in its title/description — no unrelated files. |
| 55 | - [ ] No secrets, tokens, connection strings, SAS URLs, or private endpoint values are present. |
| 56 | - [ ] Generated-data PRs do not include source code changes. |
| 57 | - [ ] Stacked PRs document their base branch and merge order. |
| 58 | - [ ] No accidentally added unrelated files are included in the commit. |
| 59 | - [ ] CI is green and tests were not weakened to achieve green status. |
| 60 | |
| 61 | ## Workflow Permissions |
| 62 | |
| 63 | - Apply least-privilege: each job declares only the permissions it needs (e.g., `contents: write` for pushes, `pull-requests: write` for PR creation, `actions: read` for status checks). Use job-level `permissions` blocks rather than broad workflow-level grants. |
| 64 | - PRs opened by automation (bot/Actions) still require human review before merge. |
| 65 | - No workflow should commit secrets or expand permissions beyond what the specific job needs. |