wp-env: Consolidating setup of the dev environment for Core and Gutenberg.

[paaljoachim]

What problem does this address?

There are different setup instructions for creating a local development environment for Core and Gutenberg. Gutenberg uses a newer wp-env method to setup a local environment. Core uses the older docker-compose created in parallell.

What is your proposed solution?

All WordPress Core development processes to use one development environment with focus on wp-env setup. We need to discover what further steps need to be taken.

Check out the discussion in this Slack thread in the meta channel in relation to a consolidation. https://wordpress.slack.com/archives/C02QB8GMM/p1611783364075700

EDIT (Added) Meta Trac ticket: https://meta.trac.wordpress.org/ticket/5581

@noahtallen @ockham @gziolo @talldan @noisysocks @dd32 @tellyworth @clorith

[noahtallen]

I think it would be great to explore how to build the core docker setup on top of wp-env. I think this would involve adding any features to wp-env which are needed to support that.

[Clorith]

I think what would essentially unblock all the things is if there was a way to control all mount points, and not just a relative path form var/www/html (the docroot of it), this would allow for custom setups to use it (think bedrock for example?), but also easy access to the xdebug profiler outputs which exists, but are not easy to get to without manually moving files inside the container after the fact.

[noisysocks]

Having a .wp-env.json file like this and then using grunt build already works quite well for Core development.

{
    "core": "./build",
    "plugins": [],
    "themes": [],
}

The work involved in getting Core to use wp-env is more about Core's continuous integration requirements. Core uses several GitHub actions for this and wp-env would need to support things like setting a specific version of PHP, running phpunit tests, etc.

[noahtallen]

specific version of PHP, running phpunit tests

We do support both of these already, though both might need to be improved depending on exactly what we need.

control all mount points, and not just a relative path form

This seems reasonable to provide too. I wonder (to keep back compatibility) we could say that any path in mappings starting with / should be treated as absolute rather than relative to docroot.

[tomjn]

For VVV and any other non-WP-Env setup, the instructions are as follows:

• go to a sites plugins folder
• git clone git@github.com:WordPress/gutenberg.git gutenberg
• cd gutenberg
• npm install && npm run build
• activate plugin in the WP Admin plugin screen

[noahtallen]

I would say that wp-env is modeled more around the plugin rather than the site, if that makes sense. So you might have a few different plugins, and each has different requirements for its development environment. (Maybe one of your plugins wishes to "depend on" the latest Gutenberg version for development, or is best developed alongside a particular theme.)

In other words, wp-env automates the prerequisites part of local environments.

[tomjn]

@noahtallen not everybody uses WP-Env, or agrees with that approach. I was asked by @paaljoachim to leave notes on this issue specifically for VVV and other environments. So I did.

I understand WP-Env is considered the golden path and canonical recommendation for Gutenberg, but that doesn't mean people who follow other paths should be censored or patronised as not understanding. Document it instead.

As for WP-Env vs docker composer, I agree, cores use of Docker should be consistent, and WP-Env appears preferable to independent docker compose usage.

Also keep in mind that setting up a dev environment for Gutenberg, and setting up a local environment, are not the same thing. E.g. staging servers, shared test environments, etc. If I want to use bleeding edge Gutenberg on Frontenberg I can't spin up WP-Env. It's not enough to just tell people to use WP-Env and let WP-Env be a magic black box, you still have to document things.

[noahtallen]

Sure! I didn't intend to imply that no other development environments should ever be used. In fact, I agree that wp-env has a fairly limited use-case and also that everyone should be able to use whatever tool they prefer. My goal was just to contrast the different goals and use-cases these projects might have. Since we're discussing wp-env as a default environment for developing core, I thought that might be valuable.

And my opinion is my own -- not a reflection of any "official" stance or decision. I completely agree with everything you said, for what it's worth.

you still have to document things.

You mention documentation a couple times -- I definitely also agree that wp-env docs could be improved. What documentation topics would you find helpful, or are there topics you've looked for that don't exist?

[tomjn]

Make sure that WP-Env is treated as a shortcut/tool/enhancement, not the build step itself. There's a trend towards treating it as a magic blackbox, and if anybody asks how it works they're told to just use WP-Env and trust it will take care of everything. Therefore why document things WP-Env takes care of.

[paaljoachim]

What are the next actionable steps that would be natural to take?

[noahtallen]

To an extent, I wonder if the magic blackbox impression is because one of the design goals is that you don't have to know how it works to use it. If someone wants to know how it works, I agree that it should be discoverable and understandable. I can see how the docs need some love in that area -- like many OSS projects, it does not receive full-time support unfortunately. I'll try to refresh them to be more clear about how wp-env works.

just use WP-Env and trust it will take care of everything

I don't know where this impression originated, but @noisysocks and myself have mentioned in the past that wp-env is specifically not supposed to take care of everything. Like, if you need an advanced setup, using Docker directly (or a different tool) is definitely a better choice.

I'll also update the docs to be more clear about that :)

What are the next actionable steps that would be natural to take?

I think it's basically just finding someone to work on it. I don't have time at the moment, so I might not be able to revisit this for a while. I think someone just needs to think about it and do some explorations. (For example, testing out current support for core development, investigating continuous integration, finding missing features that devs commonly use.)

[tomjn]

I've encountered other official WP projects where I've been told to just use WP-Env where other options are not considered/mentioned precisely because of WP Env, or non-WPEnv usage has been declared unsupported, I shan't name names.

Of note there's no documentation on this repos readme or linked from the readme for building Gutenberg itself. I'm sure it exists but it's buried somewhere offsite.

Given that Gutenberg uses WP-Env already, is this issue in the best place? There should be a Trac ticket for core itself.

[noahtallen]

I've encountered other official WP projects where I've been told to just use WP-Env where other options are not considered/mentioned precisely because of WP Env, or non-WPEnv usage has been declared unsupported, I shan't name names.

That's disappointing. I understand why that would be frustrating. To be super clear, I agree that no project should require someone to use their setup. I can understand having a default setup, and mostly supporting that, but that shouldn't mean that other setups are unsupported or blocked.

Of note there's no documentation on this repos readme or linked from the readme for building Gutenberg itself. I'm sure it exists but it's buried somewhere offsite.

I mean, wp-env development doesn't require you to build Gutenberg, nor does building (or developing for that matter) Gutenberg require wp-env. Gutenberg is as independent from wp-env as any other project utilizing wp-env. wp-env docs are linked to from Gutenberg's code contribution guide. wp-env is just taking advantage of the Gutenberg monorepo setup for tooling and having extra eyes around :)

Given that Gutenberg uses WP-Env already, is this issue in the best place? There should be a Trac ticket for core itself.

that makes sense to me 👍

[tomjn]

Trac ticket: https://meta.trac.wordpress.org/ticket/5581

[paaljoachim]

Any thoughts on movement on this issue?

[paaljoachim]

This issue is over 2 years old. Is it still valid or should I close it? The same goes for the meta trac ticket.

[noahtallen]

I still think it's a fantastic idea, but it'd require someone with the time to take it up as a project -- which unfortunately isn't me :(