- Introduces a required build step for WordPress develop. This means it will no longer be possible to run WordPress from the
src directory, but I’ve taken multiple steps to make this transition acceptable and as smooth as possible, described below.
src/js and is organized in an improved directory structure that gives much more context and is future compatible. In production, everything is built back into its original location to ensure backwards compatibility.
- Read a summary of all changes in this comment.
Here’s an overview of the directory structure that comes with the patch and the idea behind it.
├── _enqueues | Any script that ends up being enqueued.
│ ├── admin | Procedural scripts ran in the admin.
│ ├── deprecated | All deprecated scripts.
│ ├── lib | All standalone lib scripts.
│ ├── vendor | All 3rd party deps that can't be managed with NPM.
│ └── wp | All scripts that assign something to the wp namespace.
│ ├── customize | Anything under wp.customize.
│ ├── editor | Anything under wp.editor.
│ ├── media | Anything under wp.media.
│ ├── utils | Anything under wp.utils.
│ └── widgets | jQuery widgets on the wp namespace.
└── media | The media library.
This approach was taken for several reasons, almost all of which have to do with improving development workflows. This is broken down into the following concerns.
- We need to maintain backwards compatibility while providing flexibility and future compatibility for modern JS development workflows.
- We need to easily distinguish scripts that are enqueued from source modules that are bundled. We need to provide freedom in working with the source and organizing it in the best way with minimal to no impact on backwards compatibility.
- We need to organize the enqueued scripts in a structure that provides more context about their scope, contents and use.
- We need to have a better process for managing dependencies and vendor scripts.
- We need to facilitate a scalable workflow for building and bundling code. (Allowing for a build step.)
- We need to lay the groundwork to publish individual JS packages to NPM straight from the WordPress source, so the entire GPL GNU General Public License. Also see copyright license. community can benefit from them.
For a more elaborate description of these concerns, please refer to the ticket.
To make this transition as smooth as possible for code contributors, we’ve taken a couple of initial steps, with more to follow.
Separate index.php in src informing developers with steps to take
We’ve added a special page that people running WordPress from source will start seeing:
As the screen says,
npm install && grunt build will be enough to trigger a build. After that, you should have a smooth development experience using
grunt watch. The wording in the notification can still be improved. I’ve created a separate ticket to improve the wording of this message.
Optimized, (much) faster
grunt watch should be a comfortable experience. Future optimizations in this area should still be possible and could make the developer experience even smoother.
- Managing dependencies
- Setting up your local development environment
These documents can be integrated into existing documentation or added to the handbook as separate entries once this patch takes effect.
In working on this, we’ve come to the conclusion that we can do a much better job at creating a seamless development experience for WordPress core. Some complexity cannot be avoided. But if we can find ways to not force that complexity onto contributors, we should do so. This patch is a good first step in enabling more modern development workflows and practices, but it also invites future iteration. To that end I’ve opened two more tickets:
The plan is for this change to be committed to trunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision., so iteration can continue. I do acknowledge that, while we work on further improvements and optimizations, trunk might become slightly less comfortable to work with. This is the point where we need everyone’s help to get it right. Any help to improve the developer experience for WordPress core is greatly welcomed. You can think of feedback in the form of comments or tickets, tooling proposals, better use of existing tooling, optimizations of the build, anything that helps make the development experience for WordPress core more seamless.