docs: add branch and generated-data PR hygiene guide (#393)
* docs: add branch and generated-data PR hygiene guide (#334) Documents branch naming, generated-data isolation, stacked PR policy, dirty worktree rules, and a reviewer checklist for hygiene-sensitive PRs. Closes #334 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: address Copilot review comments on PR #393 - Clarify workflow permissions: job-level least-privilege, not blanket contents-write-only (workflows may need pull-requests:write, actions:read) - Rephrase checklist item: 'no accidentally added unrelated files' instead of confusing 'no stray untracked files committed' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Juan Manuel Servera committed
Jun 12, 2026 at 05:42 UTC
77a5bfce208f9817aba50ceec7f10487efc6998f
1 file changed
+65
docs/branch-pr-hygiene.md
new
+65
@@ -0,0 +1,65 @@
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.