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

Fri Feb 13 19:11:08 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):

 My apologies in advance for sounding disheartened. I recognize that we are
 all striving for the same goal of making WordPress better for everyone.
 But I'm currently unable to work with `wordpress-develop` at all and I'm
 finding the developer experience incredibly frustrating.

 It's very difficult to follow through the process to figure out where the
 issue actually is, what changes have been made to related code, etc. I
 recognize some of this is due to my own personal habits, but this is how I
 have been investigating.
 - Figure out what the error is saying.
 - Search `wordpress-develop` code base for the command that is failing.
 - Nothing is found, so I search the Gutenberg directory.
 - Find the command that's failing.
 - Look up when the pinned SHA value last changed in `wordpress-develop`.
 - Try to find changes possibly related to this error in the `./gutenberg`
 folder.
 - The clone in the `./gutenberg` directory only has a depth of 1, so while
 the `git log` is accessible, tools like `git blame` do not show accurate
 information and I'm unable to see the specific commits responsible for
 changing a given line or when the last time each line was modified.
 - I either switch to GitHub.com to look into this, or switch to the other
 checkout of Gutenberg I have in my `src/wp-content/plugins` directory. But
 this is separate, s now I need to make sure I have `trunk` checked out and
 the latest changes pulled.
 - The latest is not installed for the build step, a specific hash is. So I
 need to look for that hash in the `package.json` file or the `.gutenberg-
 hash` file and check out that revision. But I deleted this file while
 troubleshooting, and because `npm install` failed, it's now not there at
 all.

 I'm also concerned that we're still finding things that are broken today.
 - The distributed hosting tests are still broken for many of the hosts
 participating. On January 13th, I noted that there were only 3
 participants that had reported results since the original changes in
 [61438] and 15 had been reporting prior. I checked the page periodically
 to make sure the number increased again, and it did return to around 12
 reporting again, but today there are now only 6.
 - There are reports of GitHub Actions workflows failing within private
 forks.
 - As stated above by @johnbillion, the GitHub Action workflows that run
 the build script were taking 30-40% longer after the changes here. That
 still seems to be the case, and I also feel that locally with just `npm
 install` taking minutes longer than it did before.

 I may be missing it, but I don't see a GitHub Actions workflow in the
 `gutenberg` repository that tests the `wordpress-develop` build script. I
 know that seems counterintuitive, but if `wordpress-develop` is going to
 run the `gutenberg` build script as part of its own, there should be some
 level of confidence that changes will not negatively affect the other
 repository before merging. The opposite was added to `wordpress-develop`
 (for testing the `gutenberg` build process within the `src/wp-
 content/plugins` directory to ensure this common contributor workflow
 continues to work as expected. I think that could also be done here.

 In many ways, it feels like this is trying to reinvent the concept of a
 monorepo without many of the benefits of having an actual monorepo:
 - Simplified dependency management: there are still two separate
 `package.json` files with different dependency sets.
 - Atomic changes across the project: changes still need to be made in
 multiple locations, and coordinating these changes feels more complicated.
 - Consistent tooling and standards: there are still two separate build
 processes. And because of how the `gutenberg` repository is pulled in, it
 feels very "black box". The standards-related tooling is also not the
 same. It's been several months, but the last time I checked there were
 several inconsistencies in how the coding standards rules were enforced.
 - Better visibility: the visibility, in my opinion, is worse with the
 current implementation. Many of the files that were under version control
 in `wordpress-develop` before are now not (block files, default
 `theme.json`, etc.), so their history has disappeared, and tracking new
 changes requires you to know where to look within `gutenberg`, and you
 need to switch between two different repositories to find any of the
 history.

 I'm not confident that all of the ripple effects have been discovered yet.

 I'm also still not clear on a few things. For example, how am I _supposed_
 to work with or contribute to the Gutenberg plugin now? My previous
 workflow of having the plugin checked out into the `src/wp-
 content/plugins` directory _should_ still work, but I'm not yet clear on
 what adjustments I need to make. I have two clones of the same repository
 in the same project folder that are frequently out of sync (the pinned
 hash intentionally lags behind).

 For the next thing, I am going to use the word "backport" in the way it's
 historically been used (merging changes from `trunk` back to a branch for
 an older version of WordPress), not how it's being used today (to describe
 merging or porting code from `gutenberg` into `wordpress-develop`). I've
 [https://wordpress.slack.com/archives/C18723MQ8/p1663682087197919
 repeatedly]
 [https://wordpress.slack.com/archives/C051Z1SKBDZ/p1688032883454959?thread_ts=1688030696.661479&cid=C051Z1SKBDZ
 requested] a different term be used to avoid confusion or accidentally
 mistaking one action for the other.

 What do these changes mean in practice for instances where a change must
 be backported to branches that do not use this new build process? For
 example, a change merged into `gutenberg#trunk` may be backported to
 `gutenberg#wp/6.8`, `gutenberg#wp/6.7`, etc., and then the resulting
 changes are published to the npm packages before updating the respective
 branches of `wordpress-develop`. The only mention of this process I see so
 far is this:

 > > We'll also need to consider whether gitignore and SVN props will need
 to be backported to branches receiving security updates to avoid the
 accidental commit of the gutenberg repo in to wp-dev.
 >
 > Since this only affects trunk, I don't think there's anything needed
 here unless I'm missing something.

 The issue here is that contributors frequently run commands like `svn
 switch '^/branches/6.8'` to work on or commit to older branches. If
 someone has `trunk` or a branch `>=7.0` checked out and runs the build
 scripts before switching to an old branch, then any newly introduced files
 and directories not under version control/in `.gitignore` will remain
 present and the contributor could accidentally add them to version
 control.

 Candidly, I am really on the fence about leaving this in. Initially it
 remained because there was time to work out the kinks. There still is some
 time, but at what point does this cross into "there is too much risk
 remaining and we need to try again in 7.1"? I recognize that changes were
 required for 7.0 features, but given the current state of things and the
 headaches so far, is this truly better than manually syncing certain PHP
 files and updating npm dependency versions as necessary?

 I keep asking myself if we're handling this differently because it's not a
 user-facing feature. I think that we are. I can't come up with a scenario
 where we would ship this to users in the state it's in. When it comes to
 the beta/RC phases of a release cycle and branching, we are essentially
 shipping the current state of the build tools to our contributors (who are
 users too). I feel like we shouldn't treat that subset of users any
 differently when it comes to deciding "readiness", especially since we
 need the tooling to be stable and maintained within each branch long term
 (until security updates are dropped for that version of WordPress).

 Climbing out of the rabbit holes I fell down investigating the current
 issue I'm experiencing, here is what I've tried and looked into so far:
 - `rm -rf node_modules` then `npm install`
 - `rm -rf node_modules gutenberg` then `npm install`
 - Triple checked that I was using the correct version of Node.js/npm.
 - At one point, I noticed that hash stored within the `.gutenberg-hash`
 file locally did not match the one defined in the `package.json` file. I
 updated the hashes to match and still encountered the issue.
 - I deleted the `.gutenberg-hash` file and the `gutenberg` directory and
 re-ran `npm install`.
 - I created an entirely fresh clone of `wordpress-develop` in a new
 directory and ran `npm install`.

 I don't know how, but I've somehow been able to change the error message.
 I now see the following:
 {{{
 sh: patch-package: command not found
 npm error code 127
 npm error path /Users/jdesrosiers/Desktop/testing/wordpress-
 develop/gutenberg
 npm error command failed
 npm error command sh -c patch-package && node ./patches/patch-xcode.js
 }}}

 I took a look, and the `patch-package` dependency is not installed in my
 `node_module` folder.

 I looked into what the command does, and it seems to apply all of the
 patches in the the `patches` directory. There is a README file in that
 directory that explains each patch, but there's no description for the
 lighthouse-related one, one is react native-related (which should not be
 relevant to `wordpress-develop`, and the RN work has been halted for many
 months now), and the `patch-xcode.js` file with no documentation.
 [https://github.com/WordPress/gutenberg/pull/26062 Looking at the PR that
 introduced it], this also seems related to React Native, so probably not
 relevant to the `wordpress-develop`.

 The package is listed in the `devDependencies` group. If I remove the
 `postinstall` script from the `package.json` file, I get the same error
 but instead about `husky` (also in `devDependencies`).

 I have to stop there for now, but the final concern I'll raise here is a
 realization I just had while trying to wrap this up. If a Build/Test Tool
 component maintainer is having this much trouble just getting started,
 what will the experience be like for a new contributor?

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