[wp-trac] [WordPress Trac] #64393: Change how we include Gutenberg in Core

Tue Feb 24 17:42:43 UTC 2026

#64393: Change how we include Gutenberg in Core
------------------------------+--------------------------
 Reporter:  youknowriad       |       Owner:  youknowriad
     Type:  task (blessed)    |      Status:  reopened
 Priority:  high              |   Milestone:  7.0
Component:  Build/Test Tools  |     Version:
 Severity:  blocker           |  Resolution:
 Keywords:  has-patch         |     Focuses:
------------------------------+--------------------------

Comment (by desrosj):

 I created #64716 as a follow-up ticket to not draw away from the main
 discussion here, but wanted to mention it to connect the two tickets as
 related.

 I noticed a few additional problems today that are pretty serious from a
 maintainability and extensibility stand point.

 ----

 First, the `page-wp-admin.php` file is being built into the `wp-includes`
 directory. This is the wrong context, it should be placed into `wp-admin`.
 I haven't audited all of the files being built and included after the
 changes here, but there are likely others.

 Is it possible to direct these files to the right location? Or does the
 build package/routes require them to be shipped within `wp-includes`?

 ----

 I also noticed that many of the functions in the built files are wrapped
 around `function_exists()` checks. While this makes sense within the
 Gutenberg plugin, this does not make sense within `wordpress-develop`. In
 the past, this was known as a "pluggable" functions, and adding new
 pluggable functions has long been prohibited for several reasons:
 - They are inflexible by nature as multiple people cannot alter the
 function at the same time. The first one loaded "wins".
 - "Plugged" versions cannot be trusted to maintain the intended core
 behavior.
 - The quality of a plugged function is unknown and therefor is unreliable.
 - It's very difficult to reliably add support for new features within a
 pluggable feature because there's no guarantee that any plugged function
 will do the same.
 - It creates significant technical debt. Once the function is shipped,
 it's nearly impossible to change the signature because plugged versions of
 the function will not be updated reliably.

 I know that the intention is not for these functions to be recognized as
 pluggable, but they essentially are because of the `function_exists()`
 wrappers. This introduces a ton of possibilities for poor and fragmented
 user experiences.

 comment:14:ticket:761 has some context about the related problems, as well
 as #8833, #11388, #18405.

 ----

 Next, I was looking at the `wp_font_library_wp_admin_enqueue_scripts()`
 function locally and was trying to find where it was maintained. A search
 came up with nothing in Gutenberg. It does note in the file header that
 the file is auto-generated and changes should be made elsewhere, but
 there's no guidance as to where.

 After trying different substrings of the function name, I
 [https://github.com/WordPress/gutenberg/blob/252fdf490b564a7a1bf579909ec03667de9d2486/packages
 /wp-build/templates/page-wp-admin.php.template#L124 finally located the
 source code] in a `.php.template` file.

 This is a significant problem for a few reasons. The first is that someone
 contributing to WordPress through `wordpress-develop` cannot easily find
 where the source code is maintained. Even searching the function name
 shows no results.

 The second is that to my knowledge, every one of the PHP coding standards
 and analysis tools that the project currently uses only scan files
 ''ending'' with the `.php`. This includes:
 - PHPCS scanning enforcing coding standards
 - PHPCBF for auto-fixing PHP coding standards issues that can be
 accurately fixed.
 - PHPCS scanning to detect potential PHP compatibility issues
 - (new in 7.0) PHPStan static analysis.

 These tools cannot process non-PHP files because tokens and substitution
 syntax will cause parse errors. If the built files were included in
 version control here in `wordpress-develop`, then the scanning could
 process them. But that doesn't prevent issues from being merged into the
 template upstream in `gutenberg`. They would only be spotted when the SHA
 hash is bumped in this repository.

 It does seem like there are inline `phpcs:ignore` statements in the code,
 and the directory is not excluded in the `phpcs.xml.dist` file. So the
 built files will be scanned if the build script has been run. But it's not
 obvious that `npm install && npm run build:dev` need to be run before
 running PHP-related scans. The GitHub Actions
 [https://github.com/WordPress/wordpress-
 develop/blob/trunk/.github/workflows/reusable-coding-standards-php.yml#L40
 workflows in] [https://github.com/WordPress/wordpress-
 develop/blob/trunk/.github/workflows/reusable-php-compatibility.yml#L41
 Core running PHPCS] do not currently run those commands, so the files are
 not currently being scanned and validated.

 When the build process has not been run, this also breaks many other
 essential development features standard in IDEs:
 - Code navigation
 - Code completion/autocomplete
 - Parameter hinting
 - Auto docblock generation
 - Quick Documentation/IntelliSense (showing the function's documentation
 on hover)
 - Real-time error detection
 - Refactoring tools like safe rename/replace.
 - Breadcrumbs showing the path to the function

 Yes, someone contributing should be expected to run the build script
 first. But some of these features are supported by GitHub through the
 browser, and that will always be broken because the repository will never
 be aware of the built source files.

 ----

 Next new concern I have is the way that scripts and styles are being
 registered and enqueued. In `wp_font_library_wp_admin_enqueue_scripts()`,
 the function returns early if the current page is not the expected font
 library. This means that WordPress is not always aware of the fact that
 the related scripts and styles are available.

 What if someone wanted to extend one of these scripts, or load the font
 library experience within a custom admin screen? That's not possible given
 the current code. Perhaps the `get_current_screen()` results could be
 manipulated in some way to force this to run, but that's not ideal and
 would likely cause many side effects.

 ----

 > these files are maintained in Gutenberg, and the source of truth for
 them is there.

 The deeper I dig into these changes to try and suggest ways to improve
 them, the more I strongly disagree with this statement from earlier on in
 the ticket.

 Until now, JavaScript files have been maintained on the Gutenberg
 repository (because they are published to npm) but the PHP files have been
 ''iterated'' on within the Gutenberg repository. The `gutenberg` repo is
 shipped as the Gutenberg plugin, which is meant to allow users to receive
 newer features faster to test. But once  PHP code is merged into
 `wordpress-develop`, it should almost entirely be removed from
 `gutenberg`.

 This also helps to test the extensibility aspects of the code. If the
 plugin can't modify something, then no one can and that should be
 improved.

 I recognize the amount of manual work merging PHP changes from `gutenberg`
 to `wordpress-develop` requires, but I strongly disagree that this attempt
 to reduce that friction is the right solution as it's created many more
 problems than it has solved. There is a genuine desire to collaborate to a
 better solution, but the path to that is not clear to me right now without
 everyone stepping back, getting on the same page, and regrouping during
 7.1.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64393#comment:157>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform