With the introduction of the WordPress Local Environment, the next step was to make this shiny new development environment available for Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ to use.
tl;dr: If you currently run ./bin/setup-local-env.sh to use the Gutenberg environment, switch to running npm run env install, instead.
Gutenberg’s Local Environment was originally an experiment in making it easy to setup a local development environment. It was a success in some ways, in that it was easier than other methods, but it was by no means easy overall, particularly for non-developer contributors. Over time, it grew into a complex set of shell scripts, with surprising interdependencies and side effects. Being written in Bash made the scripts harder to maintain, and limited the potential audience to those who had a Bash-compatible terminal installed.
Basing Gutenberg’s Local Environment on Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’s has several immediate advantages:
- It’s cross-platform, only requiring Docker to be installed and running. It also works with Docker Toolbox, allowing all Windows users (not just those with Windows 10 Pro) to use it.
- The WordPress environment uses Docker images that we maintain for the purpose of Core development, which allows us to to customise them as we need.
- It ensures that tests for Core and Gutenberg run in the same environment.
- It’s a single environment, which helps avoid the naming clashes we’ve occasionally seen between the Core and Gutenberg environments.
More broadly for WordPress in the long term, tying the development processes of Core and Gutenberg a little closer together helps pave the way for the processes to merge over time.
Architectural Decisions
Removing the Docker config from Gutenberg entirely (barring a minimal template to hook into the Core environment), and requiring wordpress-develop to run on top of gives us significantly more future flexibility with the development environment.
Additionally, this continues to lay the groundwork for an environment that works as easily as possible for non-developer contributors. In particular, this environment is intended to be usable by all feature plugins, allowing them to easily enable new contributions in a familiar environment. (Or, an environment that will become familiar, at least. 😉)
There are several reasons for putting the main Docker config in Core, and extending it in Gutenberg:
- Having a single
docker-compose.yml file in Core, as opposed to having one in Core, one in Gutenberg, and many more in other feature plugins that will be able to use this, means that there’s only set of Docker containers running. Docker has been observed getting a little weird when trying to run containers with the same names, which mount volumes with the same names. - Having multiple
docker-compose.yml files doesn’t lend itself to testing plugins together: each plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party ends up with its own environment which can’t talk to others. - Managing how plugins can mount older versions of WordPress becomes exponentially more difficult if the
docker-compose.yml config needs to work for every WordPress branch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". (this is a requirement, so that auto updates can be worked on in old branches), rather than being able to tweak the config for each branch. - Ideally, feature plugins shouldn’t need to do much customisation of the Docker environment, beyond mounting their particular volumes. Exposing the entire
docker-compose.yml file is overkill.
That said, not every Gutenberg contributor will have a WordPress source clone, or want to manage one. So, there’s also a helper which will download and install a copy of the WordPress source repo, when needed.
Much like the WordPress environment, however, the Gutenberg environment doesn’t automate everything. As we found with the original Gutenberg environment, too much automation tended to make it difficult (particularly for more advanced contributors) to customise or debug their environment. For example, the scripts no longer install NVM, switch your Node version, or run npm install.
Using the Gutenberg Local Environment
If you don’t have a WordPress repo to work with, just run npm run env install, that’ll take care of downloading WordPress, building it, and connecting Gutenberg into it.
If you prefer to hook into your own WordPress source checkout (particularly useful for fixing issues that span Core and Gutenberg), set the WP_DEVELOP_DIR environment variable to your WordPress source directory, and run npm run env connect. This will write a docker-compose.override.yml file to the WordPress source directory, and restart the Docker containers. The Docker override file contains the appropriate volume settings for mounting Gutenberg within the WordPress environment.
Running npm run env will give you a complete list of the available commands, and what they’re for.
The WordPress Local Environment configuration options are also available for configuring the Gutenberg environment.
Adding the Local Environment to another feature plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins.
The @wordpress/scripts documentation includes information about including and configuring the local environment.
There currently isn’t a clean method for sharing a managed WordPress checkout (ie, one installed by npm run env install) between plugins. Let’s figure out how that could work!
Also, this process is still mostly untested, so please ping The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me earlier rather than later if you run into problems. 🙂
Developing Plugins/Themes with the Local Environment
At this stage, the Local Environment is intended for developing Core, and Feature Plugins: it doesn’t have the config options that the wider plugin/theme ecosystem needs, and the base Docker images are built for Core purposes.
Of course, I know y’all will try to use it, anyway. 😉 Testing and feedback is welcome, but please be aware that fixes and features will prioritise Core/Gutenberg requirements for the foreseeable future. Patches and PRs which recognise and allow for this are the best way for additional changes to land. 💖
What’s Next?
Please try out the new Gutenberg Local Environment, and report any issues you run into over on the Gutenberg repository.
If you have thoughts about making this aspect of contributing to Core/Gutenberg easier, I’d love to hear about them!
#block-editor, #gutenberg
