Docs: add the wp-build porting checklist

[CGastrell]

Fixes JETPACK-2575

Proposed changes

• Adds docs/wp-build-porting-checklist.md, a ten-section checklist for moving a Jetpack admin dashboard onto the wp-build pipeline.
• The checklist already existed, spread across four Linear comments that disagreed with each other in places. This folds them into one document, applies the three correction comments, and adds what the ports since have taught us.
• Every item cites the PR, file or issue where the trap was found. Items with no evidence behind them were left out.

Covered, each one something a port already got wrong: project wiring and the three build scripts that build:wp-build alone does not give you; bare Sass and JS specifiers, which esbuild will not resolve; loader ordering; aliasing the screen ID and restoring it; the two independent JITM failure modes; passing initial state to an ES-module page; assets; the fallback predicate; the seven verification steps; and retiring the flag promptly.

No changelog entry: docs/ is outside projects/.

Related product discussion/links

• JETPACK-2575, and JETPACK-2566, which this unblocks.

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

No. Documentation only.

Testing instructions

This is one new Markdown file and nothing else, so there is nothing to run.

• Read docs/wp-build-porting-checklist.md.
• Spot-check the citations against the code. Useful ones: the alias/restore pair in projects/packages/backup/src/class-jetpack-backup.php:1218 and :1235, the JITM slot rendered inside the app at projects/packages/my-jetpack/_inc/components/my-jetpack-screen/index.jsx:204, and the shared fallback predicate at class-jetpack-backup.php:1292.
• If you have ported a dashboard, check §4 and §5 against what you hit. Those are the two sections where a wrong line costs the next porter the most.

🤖 Generated with Claude Code

[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!

[CGastrell]

Review

Verdict: one blocker, one suggestion — both fixed in 6679bef.

All ten file:line citations were checked against origin/trunk (1a0f992) and are correct: the Backup alias/restore pair, is_backup_admin_request(), is_wp_build_dashboard_active(), render_connection_initial_state(), both JITM slots, get_message_path(), jitm_view_client, the SEO inject_script_data() comment, and the apiRoot/apiNonce defaults.

[blocker] §8 pointed at a function Search no longer has

"Search's is_wp_build_dashboard_active() is the pattern" — that symbol exists only in projects/packages/backup/src/class-jetpack-backup.php. #52416 did add it to Search, and #52506 deleted it with the legacy bundle. §8's own last bullet cites #52506, so the section contradicted itself.

The add_wp_admin_submenu() claim was wrong for a second reason: those two branches choose between a visible menu item and a hidden page, not between wp-build and legacy.

Fixed:

• Bullet 1 attributes the shared predicate to Jetpack_Backup::is_wp_build_dashboard_active() and scopes it to "while the port still has a legacy branch to choose between".
• Bullet 2 drops its repeat of the same symbol and line range, now that bullet 1 names it once.
• Bullet 3 swaps the fallback example from Search to Backup, which still dual-ships, and adds Search's real post-retirement shape: loading gated on is_search_admin_request() plus file_exists( build/build.php ), render() on function_exists() alone.

[suggestion] Nothing linked to the doc

docs/ has no index, so the next porter finds this only by grep. Added a bullet in docs/monorepo.md § Building, next to the webpack-config bullet, as its esbuild counterpart.

Not fixed

• The doc leans on file.php:1234 citations throughout, which is the "provenance that rots" shape AGENTS.md warns about — the blocker above is that already happening. Symbol names survive edits and git grep finds them; line numbers buy nothing. Worth a follow-up, out of scope here.
• "Proposed changes" still says one new file. It is two now.

— Terminator

[dhasilva]

A useful consolidation. Most citations check out at this SHA: the Backup alias/restore/predicate lines, the JITM get_message_path() and jitm_view_client lines, SEO's inject_script_data(), the AdminPage defaults, the generated template's admin_init interceptor, #wpbody-content hide rule and gutenberg_ default prefix, and every cited PR. The inline comments cover a few claims that don't match the tree, a self-contradiction in §8, and some traps the checklist doesn't list yet.

Verdict: Minor issues — can merge after addressing.

See inline comments.

Generated by Claude.

[CGastrell]

All ten applied in 27db12e, each one re-checked against trunk first.

Corrections: pagenow moved to the old-pattern sentence, five ports to seven, JITM container cited from Social's and Boost's page shells with a new bullet on the keepMounted trap, apiRoot narrowed to @automattic/jetpack-api, the i18n item now names SEO, Podcast and Scan as still unfixed, §8 split so a new route errors and a retired port renders nothing, and Linear links reduced to bare IDs. The flag paragraph now names Feature_Flags, with a note that the shipped ports' bare rsm_jetpack_ui_modernization_* filters are the older pattern.

Additions: polyfills package in both manifests, .gitattributes, the route.scss import, a shared multi-route mixin, the Safe Mode banner, and the legacy entry's side effects.

Two deviations. The port-list command pipes through cut -d/ -f1-3 | sort -u — the bare glob returns 32 route files across 16 projects. And the two stylesheet bullets went to §2 rather than §7, which is images and url().

Search's container sitting inside a tab panel is a live bug, not a doc one. Filing it separately.

— Terminator

[CGastrell]

Filed the Search tab-panel bug as JETPACK-2753. The container sits inside <Tabs.Panel value="overview">, which unmounts when the tab is inactive, so Settings and AI Answers fetch JITMs with nowhere to render them. Fix is the move #52471 made for Social.

— Terminator