WP Build Polyfills: describe the WordPress 7.0 floor in comments

[dhasilva]

Fixes JETPACK-2684

Proposed changes

Comments and docs only. No behaviour change.

Every project now requires WordPress 7.0 (MIN_WP_VERSION in .github/versions.sh, JETPACK__MINIMUM_WP_VERSION), but comments across wp-build-polyfills still argued from a 6.9 floor, and several reached conclusions the code no longer does. Each rewritten claim was checked against the WordPress 7.0 tag source.

• File header: at 7.0 and the default threshold, only wp-private-apis and wp-rich-text replace Core's copies. Every other polyfill fills a gap in Core, or replaces a Gutenberg copy too old to use.
• SCRIPT_DEPENDENCIES: 7.0's private-apis allowlist omits @wordpress/views and @wordpress/compose. It does allow @wordpress/theme, and 7.0 registers wp-theme itself.
• $hooked: it means registration has run or been hooked, not "the hook has been added", which is false on the synchronous path.
• wp_default_scripts "fires once": it fires when wp_scripts() creates the singleton, and again on init if that happened earlier.
• Per-handle rationales for wp-notices, wp-private-apis and wp-rich-text now state the 7.0 facts.
• Other files: 6.9 references removed or corrected in class-wp-build-admin-frame.php, webpack.config.js, bin/stamp-textdomains-lib.js, src/js/load-i18n-catalogs.ts, the rich-text private-APIs JS test, and one PHP test comment.
• README: the problem statement describes 7.0. Core's wp_default_scripts callback runs at the default priority 10, not 0. The module table now lists @wordpress/widget-primitives, the one module that can replace an older Gutenberg's copy instead of being ignored as a duplicate.

One correction to the issue's own premise: wp-views is not a no-op at 7.0. Core 7.0 doesn't register it, so the polyfill fills it in.

Deliberately left alone: register()'s docblock line "the highest threshold wins", which became true with #52470.

Related product discussion/links

• JETPACK-2684, split from JETPACK-2576 and raised in review on Webpack config: replace the duplicated @wordpress/ui bundling block with an opt-in option #52207.
• Stale 6.9 comments remain outside this package (Newsletter's class-settings.php, the AI Hub page, Forms, mu-wpcom). They are not part of this PR.

Does this pull request change what data or activity we track or use?

No.

Testing instructions

• Run jp test php packages/wp-build-polyfills and jp test js packages/wp-build-polyfills. Results should be unchanged.
• Spot-check the rewritten claims against the WordPress 7.0 tag:
  • wp-includes/default-filters.php: wp_default_scripts is added with no priority, so it runs at 10.
  • wp-includes/class-wp-scripts.php: the constructor runs init() and also hooks it to init at priority 0.
  • wp-includes/js/dist/private-apis.js: the allowlist includes @wordpress/theme and @wordpress/ui, but not @wordpress/views or @wordpress/compose.

🤖 Generated with Claude Code

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the update/jetpack-2684-polyfill-rationales branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/jetpack-2684-polyfill-rationales

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/jetpack-2684-polyfill-rationales

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[jp-launch-control]

Code Coverage Summary

Coverage changed in 4 files.

File	Coverage	Δ%	Δ Uncovered
projects/packages/wp-build-polyfills/bin/stamp-textdomains-lib.js	245/245 (100.00%)	0.00%	0 💚
projects/packages/wp-build-polyfills/src/class-wp-build-admin-frame.php	59/59 (100.00%)	0.00%	0 💚
projects/packages/wp-build-polyfills/src/class-wp-build-polyfills.php	140/142 (98.59%)	-0.04%	0 💚
projects/packages/wp-build-polyfills/src/js/load-i18n-catalogs.ts	511/528 (96.78%)	-0.01%	0 💚

Full summary · PHP report · JS report