feat(upstream): add commit-level triage and weekly watch for forks (#305) (#320)

Forks tracking this template face a weekly "which of these commits do I
actually care about?" question. check_upstream_updates.py answers it at the
file level (version stamps); this adds the commit-level half.

tools/upstream_triage.py walks the commits a fork is behind and splits them
into "worth reviewing" and "probably skip". Work already ported drops off on
its own via git patch-id, commits touching only files the fork removed are set
aside, and SHAs in .github/upstream-wontport.txt stay hidden. It reports and
nothing more - ready-to-run cherry-pick lines, but no merge, push, or PR,
since on a fork "applies cleanly" is not "correct".

.github/workflows/upstream-watch.yml runs it weekly into one rolling issue. It
no-ops on the upstream template (guarded, and pinned by a test) and uses only
the built-in GITHUB_TOKEN, so it can never write outside its own fork. The two
tools point at each other in their output; README, SETUP 8, and CHANGELOG
introduce them together. Tests cover patch-id matching, relevance filtering,
the won't-port list, and the workflow guard - all offline.

Co-authored-by: Angelina Lok <angelina@chattermill.io>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Angelina Lok
2026-08-11 19:11:24 +02:00
committed by GitHub
co-authored by Angelina Lok Claude Opus 4.7
parent cfd9a9fba1
commit 670d30ae7e
8 changed files with 547 additions and 3 deletions
+13
View File
@@ -15,6 +15,19 @@ per-file diff commands.
### Added
- **Commit-level upstream triage for forks** (#305). A new `tools/upstream_triage.py` walks the
commits a fork is behind upstream and sorts them into "worth reviewing" vs "probably skip":
cherry-picks already applied drop off on their own (matched by `git patch-id`, so ported work
needs no bookkeeping), commits that only touch files the fork removed are set aside, and SHAs in
a flat `.github/upstream-wontport.txt` stop resurfacing. It's the commit-history companion to
`check_upstream_updates.py`'s version stamps - the two cross-reference each other in their output.
Report-only by design: it prints ready-to-run `git cherry-pick` lines but never merges, pushes, or
opens a PR, because on a fork "applies cleanly" isn't "correct". A `.github/workflows/upstream-watch.yml`
runs it weekly into a rolling issue, guarded to no-op on the upstream template (pinned by a test) and
scoped to the built-in `GITHUB_TOKEN` so it can never write outside its own fork. SETUP.md 8
introduces both tools side by side. Offline tests cover patch-id matching, relevance filtering, the
won't-port list, and the workflow guard. Thanks @anjolok1997.
- **`security_guards.py` now holds `.claude/settings.json` hooks to an allowlist** - the
guard read `permissions.allow` and nothing else, so a `hooks` block in the same file
passed silently. A hook is strictly more dangerous than a pre-approved permission: a