An opt-in upstream-triage workflow for forks

[anjolok1997]

You mentioned in #300 that the sync-triage tool on my fork might be worth generalizing, and to float the shape here first, so here goes.

The itch it scratches: keeping a fork synced with a fast-moving upstream is mostly a "which of these 20 commits do I actually care about?" question, every week.

check_upstream_updates.py catches framework_version bumps, but it doesn't look at the commits themselves, so I was still reading each one by hand. This is what I built to stop doing that.

What it does

Report-only — it never merges, pushes, or touches code. It writes a rolling issue on my own fork sorting the commits I'm behind into worth reviewing and probably skip, using:

• Already ported? Cherry-picks keep the same patch, so it matches on git patch-id — anything I've pulled in drops off the list on its own.
• Relevant at all? Commits that only touch files I've removed, or that are changelog-only for me, get set aside with a reason.
• Already said no? A flat .github/upstream-wontport.txt lists commits I'm never porting, so they stop resurfacing.

Each commit links to its upstream diff, so reviewing is one click.

It sits alongside check_upstream_updates.py rather than replacing it — version stamp vs. commit history. (Whether they should be one tool is a question below.)

On generalizing it

The reason I think it ports easily: there's nothing UK-specific in it. It derives everything from git at runtime, no hardcoded paths (only literal is CHANGELOG.md).
The fork-specific pieces all live in the workflow — the upstream remote, the schedule, and the self-triage guard.

Open questions

1. Where it lives — I'd ship the workflow in .github/workflows/, guarded so it no-ops on the template itself (forks inherit it, stays opt-in). That matches how check_upstream_updates.py already works. Downside is the template carries a workflow that never runs there — if you'd rather avoid that, a documented copy-in works too. No strong preference either way.
2. How far to automate — I'd stop at report-only, maybe with ready-to-run cherry-pick lines or a draft PR, but not auto-merge. On a fork, "applies cleanly" isn't "correct" — a commit for portals I dropped can cherry-pick fine and still be wrong, and that silent-wrong case is worse than a conflict.
3. One tool or two — keep it separate from check_upstream_updates.py, or merge them?
4. The won't-port list — it's a flat SHA list today. Worth growing into the config-driven divergence manifest you mentioned (removed-area globs auto-skipped, rewritten files flagged), or better kept simple?

One fix worth having regardless: an early run of mine posted its report into your issues (#300) — sorry about that. It was using a cross-repo PAT; switching to the built-in GITHUB_TOKEN means it can't write outside its own repo, so no fork can repeat it.

[MadsLorentzen]

This is exactly the shape I hoped for when I suggested floating it here first - thank you for doing the design write-up rather than opening with a PR. The core insight holds up: check_upstream_updates.py answers "which of my personalized files changed" and yours answers "which commits deserve my attention", and those really are different questions. The git patch-id matching is the part that makes it genuinely good rather than merely convenient - ported work dropping off the list with zero bookkeeping is what makes a weekly report stay readable for months. And your automation instinct ("applies cleanly isn't correct, and silent-wrong is worse than a conflict") is this repo's own posture stated better than we've stated it.

I'd welcome the PR. Answers to your four questions:

1. Where it lives: in-tree, guarded. Ship the workflow in .github/workflows/ with the no-op-on-upstream guard, matching how the four Danish portals now ship disabled: the capability travels with the fork, activation is a deliberate act. GitHub gives us the opt-in structurally for free - inherited workflows sit disabled on a fork until the owner enables Actions - so the guard is a second fence, not the only one. The template carrying one inert workflow is a price worth paying for every fork inheriting the tooling without a copy-in step.

2. How far to automate: report-only, and stop before draft PRs. Ready-to-run git cherry-pick lines in the report are welcome - that's still information. A draft PR is repository state created without a human deciding, which crosses the line this project keeps everywhere else (the same reason /apply drafts but never submits). Your report/act boundary is the right one; let's write it into the workflow's doc comment so it survives future contributors.

3. One tool or two: two. check_upstream_updates.py is stable, shipped, and answers its question well. Coupling it to a new tool buys nothing and risks both. A cross-reference in each one's output ("for commit-level triage, see ...; for personalized-file version stamps, see ...") gets the discoverability without the coupling.

4. Won't-port list: keep it flat. A SHA list is auditable at a glance and hard to get wrong. Add removed-area globs only if fork maintainers actually ask for them - the divergence manifest can stay an idea until demand shows up. (Your own relevance filter already auto-skips commits touching files the fork removed, which covers most of what the manifest would.)

The bar for the PR, same as everything that lands here:

• The upstream guard pinned by a test: prove the workflow no-ops when the repo is MadsLorentzen/ai-job-search, so a template clone never runs it by surprise.
• Offline tests for the triage logic (patch-id matching, relevance filtering, won't-port exclusion) against fixture git history - no network in CI, same as every portal CLI.
• Actions SHA-pinned, GITHUB_TOKEN only, writes scoped to the fork's own repo - which your fork's current version already does since the Upstream sync watch #300 fix, so this is "keep it that way", not new work.
• CHANGELOG entry + a short section in SETUP.md 8 (Pulling upstream updates) introducing the two tools side by side.

And since it will carry your name in the workflow file: thank you for the #300 root-cause follow-up. Finding your own bug, stating it publicly, and fixing the class rather than the instance is the contributor behavior this thread exists to surface.

[MadsLorentzen]

Closing the loop for anyone finding this thread later: the PR landed as #320 and ships in-tree as of 670d30a - .github/workflows/upstream-watch.yml (guarded no-op on upstream, weekly Mon 08:00 UTC on forks that enable Actions) plus the commit-level triage tool, exactly the report-only shape settled above.