CI: Add "Required changes from trunk" PR check

[manzoorwanijk]

What?

See #80395 (comment).

Adds a "Required changes from trunk" check: a movable required-trunk-baseline tag marks the last trunk commit every open PR must contain, and a workflow stamps each PR with a passing or failing commit status against it.

Why?

Repo-wide infrastructure changes (toolchain bumps like Node.js 24, formatting or linting changes) invalidate open PRs silently: they keep passing stale checks or sit on "Expected" forever. This turns that into an actionable "merge or rebase trunk" signal.

How?

The baseline moves only through explicit maintainer intent: dispatching the workflow with move-baseline: true, or merging a PR that carries the Require PR update label. After a move, stale passing statuses are flipped to failing.

• .github/workflows/required-changes-from-trunk.yml: pull_request_target stamps each PR; a second job moves the tag and fans out.
• tools/validation/required-trunk-changes/: check, move-baseline, and fanout subcommands with rate-limited status writes.
• docs/contributors/code/required-changes-from-trunk.md: model, limits, and runbook.

Testing Instructions

1. npm run --workspace @wordpress/validation-tools required-trunk-changes prints usage.
2. With GITHUB_TOKEN and GITHUB_REPOSITORY set, append -- fanout --dry-run to list intended writes without posting.
3. npm run test:unit -- tools/validation/required-trunk-changes and npm run lint:js -- tools/validation/required-trunk-changes pass.

Testing Instructions for Keyboard

Not applicable, no UI changes.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: jsnajdr <jsnajdr@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: 0 B

Total Size: 7.91 MB

_{compressed-size-action}

[Copilot]

Pull request overview

Adds an infrastructure-baseline status check that requires open PRs to contain designated trunk changes.

Changes:

• Adds workflows and tooling to move, check, and reconcile the baseline.
• Adds rate-limited GitHub status updates.
• Documents contributor and maintainer workflows.

Suggested tests: CLI usage, conflicting PR transitions, concurrent baseline movement, and write-budget exhaustion.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
.github/workflows/pr-is-up-to-date.yml	Runs freshness checks and reconciliation.
tools/validation/pr-freshness/check.mjs	Checks one PR against the baseline.
tools/validation/pr-freshness/fanout.mjs	Reconciles statuses across open PRs.
tools/validation/pr-freshness/index.mjs	Implements command-line dispatch.
tools/validation/pr-freshness/move-baseline.mjs	Detects and performs baseline moves.
tools/validation/pr-freshness/types.mjs	Defines shared JSDoc types.
tools/validation/pr-freshness/utils.mjs	Provides Git, API, and status helpers.
tools/validation/package.json	Exposes the freshness command.
docs/contributors/code/pr-freshness.md	Documents the freshness system.
docs/contributors/repository-management.md	Documents the force-refresh label.
docs/manifest.json	Registers the guide metadata.
docs/toc.json	Adds the guide to navigation.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ciampo]

This is a bit out of my expertise, and therefore the majority of my comments were actually flagged during an AI assisted review.

[github-actions]

Flaky tests detected in 2831743.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/33463587475
📝 Reported tests:

Should save the changes in /test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js, passed after 2 failed attempts.

TimeoutError: page.waitForFunction: Timeout 10000ms exceeded.
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:34:14
TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for locator('role=button[name="Visual"i]')

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:33:55

[Mamaduka]

This reminds me of #76820. Sure, it's useful, but a contributor can easily address it on a personal level. Plus one less tool we have to maintain. GitHub already shows some indicators that branches are out of sync.

IMO, the project-wide changes should always be announced in Slack or on the Make blog.

[manzoorwanijk]

This reminds me of #76820. Sure, it's useful, but a contributor can easily address it on a personal level. Plus one less tool we have to maintain. GitHub already shows some indicators that branches are out of sync.

That is true but not always helpful and not very clear. It shows that your branch is out of date even for a single commit in trunk, which we mostly ignore.

IMO, the project-wide changes should always be announced in Slack or on the Make blog.

That is true but not all the contributors actively look at them while working on PRs. This is kind of a gentle nudge to point them in the right direction.

[Mamaduka]

That is true but not all the contributors actively look at them while working on PRs. This is kind of a gentle nudge to point them in the right direction.

In my experience, most action bot comments also get ignored on PRs 😅

[ciampo]

GitHub already shows some indicators that branches are out of sync.

That is true but not always helpful and not very clear. It shows that your branch is out of date even for a single commit in trunk, which we mostly ignore.

I find that information a bit useless, given the frequency of commits on trunk in Gutenberg

[github-actions]

🤖 PR meta 🤖

📦 Bundle size

Size Change: 0 B

Total Size: 8.01 MB

_{0a6334f Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	35929d1	trunk	% Change
timeToFirstByte	51.5 ms +11.26% -6.41%	49.05 ms +12.33% -7.65%	4.99%
largestContentfulPaint	82 ms +9.76% -4.88%	80 ms +2.5% -5%	2.5%
lcpMinusTtfb	30.3 ms +6.6% -4.29%	28.5 ms +21.75% -8.42%	6.32%
wpBeforeTemplate	23.79 ms +16.77% -7.15%	22.82 ms +16.21% -9.33%	4.25%
wpTemplate	22.74 ms +7.65% -3.74%	22.07 ms +7.29% -5.8%	3.04%
wpTotal	47.86 ms +11.03% -6.69%	45.75 ms +10.84% -8.11%	4.61%
wpMemoryUsage	7.54 MB +0% -0%	7.50 MB +0% -0%	0.46%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	35929d1	trunk	% Change
timeToFirstByte	40.65 ms +12.3% -4.18%	39.65 ms +9.46% -6.31%	2.52%
largestContentfulPaint	80 ms +17.5% -0%	76 ms +10.53% -0%	5.26%
lcpMinusTtfb	40.85 ms +4.28% -3.55%	38.85 ms +3.86% -6.44%	5.15%
wpBeforeTemplate	19.45 ms +9.51% -3.39%	19.77 ms +10.42% -8.35%	-1.62%
wpTemplate	18.02 ms +7.55% -3.94%	16.46 ms +6.01% -3.83%	9.48%
wpTotal	37.67 ms +11.18% -4.17%	37.11 ms +9.11% -7.41%	1.51%
wpMemoryUsage	6.16 MB +0% -0%	6.12 MB +0% -0%	0.58%
wpDbQueries	14 +0% -0%	14 +0% -0%	0%

media-processing

Metric	35929d1	trunk	% Change
mediaProcessingJpeg	329.94 ms +1.45% -1.74%	338.36 ms +2.87% -1.19%	-2.49%
mediaProcessingAvif	5061.92 ms +1.14% -0.33%	5080.79 ms +0.66% -0.96%	-0.37%
mediaProcessingJpegToAvif	3552.3 ms +0.94% -0.33%	3538.32 ms +0.5% -0.39%	0.4%

media-upload

Metric	35929d1	trunk	% Change
jpegUploadProcessing	1416.62 ms +1.81% -2.13%	1395.27 ms +0.87% -1%	1.53%
pngUploadProcessing	191.17 ms +1.47% -7.82%	179.46 ms +6.31% -2.31%	6.53%
largeJpegUploadProcessing	1397.06 ms +0.55% -0.22%	1404.39 ms +0.28% -0.36%	-0.52%
multipleImageUploadProcessing	1490.59 ms +7.8% -1.27%	1467.95 ms +1.46% -0.53%	1.54%

post-editor

Metric	35929d1	trunk	% Change
serverResponse	459.72 ms +2.92% -7.08%	449.35 ms +3.71% -7.02%	2.31%
firstPaint	236.73 ms +22.88% -21.77%	226.83 ms +11.11% -19.59%	4.36%
domContentLoaded	1291.48 ms +2.68% -1.79%	1326.14 ms +1.23% -4.08%	-2.61%
loaded	1292.82 ms +2.68% -1.79%	1327.59 ms +1.22% -4.07%	-2.62%
firstContentfulPaint	430.86 ms +6.47% -3.84%	435.18 ms +2.17% -6.4%	-0.99%
firstBlock	3483.84 ms +0.58% -0.93%	3499.46 ms +2.27% -1.51%	-0.45%
type	20.38 ms +17.17% -12.51%	20.69 ms +9.33% -16.48%	-1.5%
typeWithoutInspector	20.42 ms +12.19% -16.5%	21.72 ms +14.5% -12.75%	-5.99%
typeWithTopToolbar	24.13 ms +11.02% -22.92%	23.56 ms +12.65% -17.28%	2.42%
typeContainer	9.43 ms +2.55% -2.76%	9.81 ms +3.57% -15.19%	-3.87%
focus	76.61 ms +15.95% -5.1%	79.96 ms +45.6% -9.78%	-4.19%
firstFocus	168.06 ms +0% -0%	168.15 ms +0% -0%	-0.05%
selectAll	586.9 ms +0.66% -1.57%	587.31 ms +2.05% -0.15%	-0.07%
listViewOpen	65.11 ms +3.64% -7.99%	68.04 ms +17.71% -6.16%	-4.31%
inserterOpen	23.39 ms +13.68% -8.94%	24.08 ms +6.06% -4.73%	-2.87%
inserterHover	4.81 ms +5.2% -15.18%	3.65 ms +11.23% -4.93%	31.78%
inserterSearch	7.71 ms +14.4% -4.02%	9.71 ms +3.5% -6.69%	-20.6%
loadPatterns	668.09 ms +1.95% -7.05%	647.17 ms +3.6% -1.76%	3.23%
wpTotal	448.81 ms +2.88% -7.23%	438.16 ms +3.75% -7.21%	2.43%
wpMemoryUsage	13.13 MB +0% -0%	13.10 MB +0% -0%	0.22%
wpDbQueries	54 +0% -1.85%	54 +0% -1.85%	0%

site-editor

Metric	35929d1	trunk	% Change
serverResponse	535.7 ms +3.51% -5.22%	525.74 ms +5.02% -4.51%	1.89%
firstPaint	251.09 ms +8.65% -7.73%	277.89 ms +5.44% -13.28%	-9.64%
domContentLoaded	1377.88 ms +1.86% -1.24%	1373.15 ms +0.87% -0.65%	0.34%
loaded	1379.04 ms +1.86% -1.24%	1374.37 ms +0.85% -0.66%	0.34%
firstContentfulPaint	435.67 ms +0.89% -2.74%	431.38 ms +2.51% -1.57%	0.99%
firstBlock	4370.27 ms +0.67% -0.33%	4363.94 ms +0.5% -0.99%	0.15%
type	19.82 ms +6.71% -10.29%	19.93 ms +15.3% -18.77%	-0.55%
navigate	101.13 ms +2.89% -10.68%	95.25 ms +2.75% -6.51%	6.17%
loadPatterns	1304.74 ms +14.67% -4.6%	1424.61 ms +13.45% -6.89%	-8.41%
loadPages	1486.48 ms +9.6% -19.53%	1159.14 ms +7.79% -0.92%	28.24%
wpTotal	526.27 ms +3.58% -5.25%	516.17 ms +5.07% -4.54%	1.96%
wpMemoryUsage	12.02 MB +0% -0%	11.99 MB +0% -0%	0.3%
wpDbQueries	43 +2.33% -0%	43 +2.33% -0%	0%

_{0a6334f Run}

[ciampo]

FWIW, I don't have additional review comments (all previous feedback was addressed).

It's now a matter of whether we believe this is a useful feature (despite the added code complexity).

[manzoorwanijk]

I think it will still be useful for other cases like when we make some changes to ESLint or Stylelint rule and merge a fix to trunk and don't want any open PRs reintroducing such lints.

[aduth]

I'm coming to this late and missing some of the original context of the changes surrounding the earlier discussion. Approaching this pull request, I was initially skeptical if this would block based on any out-of-date branch, and the potential complexity of ~1k LOC. But I also do think this solves a real issue, and the "moving baseline" approach is pretty clever as a way to establish milestones in time without requiring everyone to keep their branch always up-to-date. Frankly I think the "branch is out of date" indicator is rarely helpful and only really serves to implicitly shift blame to the pull request author if anything goes wrong in the merge. And personally I've felt that Slack messages in #core-editor can be helpful but that the audience is incomplete and may easily be missed.

I guess the bulk of the complexity comes down to invalidating existing checks after the baseline shifts, but the actual comparison itself is pretty straight-forward. And it does feel complex. Maybe that's acceptable, maybe there's some compromise or simpler solutions to explore. A few thoughts come to mind :

• Using a static file for comparison rather than a workflow for moving the baseline
• Using merge queues to do the check at merge time
• Searching only pull requests with some recent activity rather than everything
• Only running the check on fresh commits / pull requests, i.e. dropping the external invalidation.
  • This loses a fair bit of the value of invalidating old pull requests, but I expect it also drops a lot of the associated complexity

tl;dr: Ultimately I'd be in favor of trying something like this.

[manzoorwanijk]

Maybe that's acceptable, maybe there's some compromise or simpler solutions to explore. A few thoughts come to mind

Thanks, that framing matches the intent well.

On the alternatives, roughly in order of appeal:

• Static file instead of the tag. Genuinely attractive: the disruptive PR bumps the file itself, which drops the tag, the dispatch and the tag ruleset, and puts the intent in the diff. It does not drop the invalidation, though, and that is where the complexity actually lives.
• Recent activity only. Cheap to add. The sweep already reads every open PR in one paginated GraphQL query and writes only to PRs holding a stale pass; a dry run across 2,466 open PRs needed zero writes. An updatedAt cutoff is a few lines if write volume becomes a concern.
• Merge queue. Considered while planning and set aside: it solves staleness properly at merge time, but it is a large process change for the project and gives authors no early signal. Nothing here blocks adopting it later.
• Drop external invalidation. That is fanout.mjs, 159 lines. Reasonable as a first phase, but an already green PR stays green and merges stale, which is the case the check exists for.

[manzoorwanijk]

What should we do about this to unblock Node 24 upgrade - #80395? IMHO, that upgrade alone is a big use-case for a change like this.

[aduth]

My recommendation would be to merge this and use #80395 as a way to validate its effectiveness.

The other option (not my recommendation) would be to merge #80395 and assess whether breakage happens without protections like this. If breakage happens, it justifies the need. If breakage doesn't happen, then this may be a premature optimization.

[manzoorwanijk]

Alright, I also lean towards moving this forward. It’s been open for a few days now with no strong objection, I’ll merge this in a while.

[manzoorwanijk]

I have created the label Require PR update. Merging this now.

[ciampo]

I'll use it for the vitest migration, too