Consider moving wp-env project to own repository

[brylie]

What problem does this address?

The wp-env utility library is currently contained within the Gutenberg project. Unfortunately, this makes it a bit difficult to find the project files and related issues/pull requests amidst the bustling Gutenberg development activity.

What is your proposed solution?

Move the wp-env project to its own repository, so code, issues, and pull requests are easier to locate/organize.

[talldan]

This issues should all be labelled - https://github.com/WordPress/gutenberg/issues?q=is%3Aopen+is%3Aissue+label%3A%22%5BPackage%5D+Env%22. Same with PRs.

If there's any missing labels, they can be labelled.

[brylie]

Issue labels are indeed useful but it still seems like a reasonable idea for the project to have its own repository. :smiley:

There is a lot of unrelated activity in this repository such as running the full Gutenberg test suite on every pull request, even when it just relates to wp-env.

Also, developers have to check out all of the Gutenberg code when wanting to only make a change to wp-env.

[gziolo]

@wordpress/env is also used for development in Gutenberg so there are also pros of keeping the source code in the same repository. There is more to it, we use one way to publish packages to npm, there is a wider group of contributors that can learn about the tool. I'm worried that the overall maintenance cost is going to be higher if we were to extract a single package to a separate repository.

[brylie]

@gziolo, in what way(s) would the NPM package publication workflow be affected by having a separate project for wp-env? What are some ways we can raise contributor awareness of wp-env? What additional maintenance costs might the wp-env project incur by being in a separate repository?

[brylie]

Relatedly, a single-line pull request for wp-env documentation is currently blocked by failing Gutenberg end-to-end tests.

I still believe that moving wp-env to a separate project repository would make development more simple and clear. In effect, wp-env is a useful tool for general WordPress (PHP) developers as well as Gutenberg developers, so would benefit from neutral positioning and streamlined :racing_car: repository structure and development workflow. :smiley:

[gziolo]

I asked more folks on WordPress Slack to leave their feedback (link requires registration at https://make.wordpress.org/chat/):

https://wordpress.slack.com/archives/C02QB2JS7/p1631001940283000

[youknowriad]

I'm on the opinion that a separate repository is just going to require more maintenance work for no real gains. The setup to publish npm is already in place here, there are already folks working and following this repo. A separate repo would require building new workflows, a new team dynamic that I don't think is worth it personally. I'm also of the opinion that all WP npm packages should just be in this repository.

The fact that e2e tests from Gutenberg can block PRs for wp-env look like a good thing to me, they're validating that wp-env changes work properly as well. Intermittent failures are an issue of course but it's a constant priority for us.

[swissspidy]

The same arguments here about running tests and finding issues could be made for other packages, not just @wordpress/env. And they are not un-solvable tasks.

https://github.com/WordPress/gutenberg is the de facto monorepo for all WordPress JavaScript packages (replacing https://github.com/WordPress/packages, if you remember that one). There are indeed benefits to keeping all these things in one place, from contributor onboarding to maintenance to publishing. Admittedly, it's a bit confusing to have a monorepo intertwined with a WordPress plugin, but there are practical reasons for that too (which is why https://github.com/WordPress/packages didn't work).

But you're posing an interesting question here:

At which point does an individual package (outgrow the monorepo and) warrant its own home?

Off the top of my head, I could think of a couple of indicators:

• Higher velocity than the rest of the project i.e. tons of contributions, frequent releases desired -> the monorepo would slow it down
• Change in direction/scope
  i.e. the package itself gathers a community on its own, pursuing higher goals (e.g. a general purpose local environment like you mentioned), warranting separate forums, documentation, etc.

Neither of the above is really the case for @wordpress/env in my opinion.

[nerrad]

Just voicing my agreement with comments that have already eloquently expressed by @gziolo, @youknowriad and @swissspidy. In particular, I appreciate the framing Pascal has put around identifying some indicators where a project might be moved into its own repository and I agree that @wordpress/env doesn't meet that criteria currently.

[Mamaduka]

I agree with Pascal's point regarding the indicators. Currently @wordpress/env package doesn't meet the criteria.

Moving also might cause a little confusion. As mentioned above, this is the de facto monorepo for all @wordpress/* packages, and people are used to creating issues/PRs here.

[bph]

This seems to be the same issue Marius Jensen raised here #32584 @Clorith

[bph]

I like that it allows for Gutenberg contributors to have it all in one package. I also can see that if someone wants to contribute only to @wordpress/env the additional payload of the fork might be an issue. The two factors, make me lean towards keeping it in its current space:

• all the documentation and instructions, would need to be rewritten. There are not many people contributing to documentation. (@youknowriad raised maintenance work, definitely worth considering)
• Gutenberg repository attract a lot more people and expose them to the @wordpress/env, a separate repository would probably not. It's a great side effect that WordPress (PHP) developers appreciate the work by Gutenberg developers on a local environment worth their while.

[brylie]

Thanks, @bph, for pointing out that this is a duplicate of issue #32584. I may not have searched for duplicate issue(s) before creating this one, although I usually do. I'm not sure how to merge the conversations, as the previous issue seems to have garnered more agreement (in terms of thumbs up).

That said, I would like to explore further a few of the points raised so far.

The fact that e2e tests from Gutenberg can block PRs for wp-env look like a good thing to me, they're validating that wp-env changes work properly as well.

The test cases that run on this repository seem mainly Gutenberg-related. Which of the tests validate that wp-env is working correctly? Are those tests somehow tied to the Gutenberg code?

all the documentation and instructions, would need to be rewritten.

I don't see much in the @wordpress/env documentation that would seem to require rewriting. Is there some other source of documentation I am missing? For example, perhaps some parts managing packages document would need to be included in a separate wp-env repository to aid in the publication workflow?

the package itself gathers a community on its own, pursuing higher goals (e.g. a general-purpose local environment like you mentioned), warranting separate forums, documentation, etc.

I also agree with this framing. However, having a separate repository doesn't imply different forums or sweeping changes to the documentation, as suggested.

The same arguments here about running tests and finding issues could be made for other packages, not just @wordpress/env. And they are not un-solvable tasks.

I agree the [Package] Env label is useful and observe the resourcefulness of Gutenberg's core engineering team. However, is it possible to exclude some of the Gutenberg tests from running on commits to the wp-env package? I.e., improve the signal/noise ratio of the CI workflow.

A separate repo would require building new workflows

What are some new workflows that would be needed? Relatedly, what are some existing workflows that might require modification?

WordPress/gutenberg is the de facto monorepo for all WordPress JavaScript packages (replacing WordPress/packages, if you remember that one). There are indeed benefits to keeping all these things in one place, from contributor onboarding to maintenance to publishing.

Thanks for the clarification about the onboarding, maintenance, and publishing. What would be some maintenance and onboarding costs of maintaining the wp-env project in a separate repository? Conversely, what might be some benefits or improvements of having independent projects?

Gutenberg repository attract a lot more people and expose them to the @wordpress/env, a separate repository would probably not. It's a great side effect that WordPress (PHP) developers appreciate the work by Gutenberg developers on a local environment

I'm concerned with relevancy and clarity. For example, when I came to this repository to change the wp-env code and documentation, I had difficulty finding the code in the packages folder among various other packages. While the Gutenberg project is a remarkable undertaking, most of the code, commit history, CI pipeline, and issues are just not salient to wp-env development.

I'm also of the opinion that all WP npm packages should just be in this repository.

In addition to WP npm and Gutenberg packages, the packages folder also includes tests (e2e-*) a lot of third-party code (like react-*, jest-*, babel-*, eslint, *-webpack-*, redux-*, docgen and is-shallow-equal). There are likely pragmatic reasons for keeping development dependencies under revision control instead of package.json, but it adds further weight to the codebase and commit-history.

Repository "clutter" is particularly undesirable when wanting to contribute to a specific environment tool (wp-env) that decoupled from both Gutenberg and WordPress core.

[gziolo]

This seems to be the same issue Marius Jensen raised here #32584 @Clorith

Great catch @bph, I closed the other issue and here is the comment from @Clorith:

Currently, the Gutenberg project is a monolith of tools and features, one of these features is wp-env, a node module for managing, and working with, WordPress plugins and themes.

Given the nature of wp-env, it is a tool with a much borader reach and audience than the Gutenberg monorepo, and as such does not (in my opinion) properly fit in here.

By splitting it out to its own repo, it becomes easier for others to adopt, learn from, and hopefully contribute back to, the tool it self.

This would also make it easier for those looking to enhance it to fork the project, without getting a block editor along as a bonus, or jsut to implement changes ahead of releases based on localized needs there and then.

I will happily admit to not knowing the technical difficulties involved in moving NPM packages to a new repositor, but I honestly believe that not bundling this broad of a tool inside the Gutenberg repository will be a positive change. There may be other such tools that I'm not familiar with, so perhaps it's a roader discussion of "separating tooling from code" in the Gutenberg repo? Would absolutely love thoughts and input on this.

[timnolte]

I will voice my desire to see this separated out as well. I've been trying to use wp-env and wp-scripts as a core development packages for plugin development instead of rolling my own local development setup. I too have had problems contributing to wp-env alone because of the massive build overhead of the entire Gutenberg project. IMO wp-env should be the defacto plugin/theme development environment supported by the community and all Core-related plugins and themes should be using it to make a more first-class citizen.

[jgreys]

Same opinion as @timnolte ! wp-env is such a great tool! :)

[brylie]

It is quite an encumbrance to install all of the Gutenberg project dependencies and any other @wordpress libraries bundled into this repository to work on a single project. The complexity of the dependencies, as well as the number of irrelevant CI tasks, is interfering with development in PR #34324

E.g. the dependencies/scripts to lint/format JS are defined in the root of the Gutenberg project instead of the packages/env/package.json

[timnolte]

I'm pretty much in total agreement with @WraithKenny if the individual packages aren't meant for anyone outside of the Gutenberg project then make that explicit, or better yet publish them in a private repo. It does seem rather ridiculous that there is so much in the wp-env package that suggests that it was designed with a broader audience in mind, but then it's stuck in a world that makes it very hard to contribute to it.

[youknowriad]

Env, Scripts, Babel-Preset, Browserllist-Config, Prettier-Config, Stylelint-Config, Eslint-Plugin and any other NPM-published package that's allegedly supposed to be useful to plugin and theme authors beyond just gutenberg, should all be separated out of this "monorepo."

The fact that all these packages are dependent on each other and evolve together most time is a great indication that the mono repo is the best path forward. You shouldn't be forced to have multiple PRs in parallel in multiple repos to make a change, or do a waterfall kind of flow. The whole open source community is evolving in this direction for these reasons. Smaller PRs for specific packages exist but more often, a PR touches multiple packages at the same time.

[nerrad]

There are no "advantages" of keeping them in the "monorepo" beyond whatever opaque npm publishing shortcuts you've invented, and there are lots of disadvantages.

Really? I see a number of advantages that have already been mentioned here. I can understand that you might not agree with the advantages that have been pointed out but that doesn't mean none have been brought up :)

The most obvious thing is "dog-fooding" which, back in the day, the WordPress community actually embraced, but is not doing here. All of these packages should be separate and consumed as a user (theme and plugin developer) would.

That's a fairly blanket statement that I'd like to provide a counterpoint from observation. I'm aware of numerous plugins and themes that utilize the packages as they are currently distributed. Just a few at the top of my mind at the moment: WooCommerce, WooCommerce Blocks, Calypso, Jetpack, Yoast SEO, Event Espresso. The fact that the Gutenberg project isn't directly pulling these packages from NPM isn't something I'd consider a hindrance. In fact, the opposite is true, I think it allows the project to react more quickly to issues (for reasons others have already pointed out in this thread) that are reported by plugin and theme authors using the packages.

Historically, WordPress has always been a monorepo in some way as far as dev tooling goes (PHPUnit tests, JS test suites, Grunt build tool, the entire "develop" WP structure is a testament to that).

But, on the second part, Gutenberg's release constraints already slow down the release of fixes to the developer packages.

I think there's some truth in this observation but more related to the delay in package updates when in the midst of a WordPress release cycle. This is already a known thing and something that will be iterated on. Outside of the WordPress release cycle, it's been my experience that the package updates are generally pretty frequent.

On the other hand, there are many efficiencies that are gained from working in a mono repo (through experience in trying both approaches) that effectively means momentum is kept in improving the packages. Efficiencies that would be lost in splitting everything out to its own repository.

---

I wonder if it'd be worthwhile to capture as a list the problems/friction contributing/consuming packages in the Gutenberg repo both to outline the tradeoffs being made currently and acknowledge that for some users this is a hindrance to making contributions. As a first step, I think it's good to have that articulated somewhere. This then can be used as inspiration for exploring how the various trade-offs might be addressed even without splitting out to a mono-repo?

[timnolte]

@nerrad I think the problem is that wp-env if it's supposed to be for plugin and theme development really shouldn't be held hostage by the Gutenberg plugin. All of what's mentioned makes me question that if the mono repo is such a good thing then why isn't Gutenberg and all of the packages put in WordPress Core. From what I've seen the reason is exactly the opposite of your cases on why wp-env should stay in this mono repo, keeping Gutenberg separate means that it can be developed faster than WordPress Core releases. Which also allows people to install this plugin which overrides the Gutenberg that is included in WordPress Core.

[youknowriad]

All of what's mentioned makes me question that if the mono repo is such a good thing then why isn't Gutenberg and all of the packages put in WordPress Core

I for one would actually love for Gutenberg and core to merge into a single mono repository. The reason it's not is that we don't want to lose all the github flavor and tooling that comes with it. Merging Gutenberg and Core doesn't prevent Gutenberg to ship a plugin (or an alpha version of WordPress) faster than Core, we're just dealing with the difficulty to more Core to GitHub or similar.

[timnolte]

Why am I not seeing the recent posts here from @WraithKenny I know they posted twice today as I got the email notifications.

[talldan]

One thing I would say is this discussion is quite long form, and a lot of the points being made are hard to digest (requires a lot of reading). The description doesn't have a summary of the relevant pain points, so it's hard to actually understand where we can make improvements.

I think it's worth looking at the reasons for wanting to move to a separate repo and see whether any of them can be addressed or at least improved while keeping the project as part of the monorepo.

For example, it was mentioned that managing issues is difficult. If there are motivated contributors, then using a project board or tracking issue are effective ways to manage a project.

If building the entire project is too slow, then we should look at options for improving that (I understand @kevin940726 @youknowriad already have been working speeding up the build), or other ideas like being able to run npm run dev for a single package only.

Why am I not seeing the recent posts here from @WraithKenny I know they posted twice today as I got the email notifications.

I'm not sure why. I also saw a notification, but the message is not here. I will mention that the constant thumbs down on every post they disagree with is really very annoying, and it doesn't constitute a positive or productive discussion. I would encourage you not to do this, it comes across as unfriendly.

[timnolte]

Basically, all I'm hearing is that the idea of moving this package, or any other NPM package in this monorepo, has been permanently turned down by powers in control. You have effectively shutdown the conversation. You might as well close this issue altogether because you have no intention of ever considering moving out of this crazy unmaintainable monorepo. At this point I think I have my answer and will no longer be investing any more of my time to improve this package. I'd rather be involved in contributing where people are at least willing to have an actual discussion about instead of just making it seem that the monorepo is the only right answer. I'm in complete agreement with @WraithKenny and unless someone can actually make a legitimate case like they have for why breaking any of these packages off to their own repos is going to hurt anything I'm done listening to the one-sided enforcement of the maintainers. Improving the monorepo doesn't improve the entire process as @WraithKenny so clearly articulated.

[talldan]

That's quite a strong reaction. Look at it on the other hand. A small group of contributors are only willing to discuss the idea of moving the package out of the monorepo, and unwilling to consider any other solution. This approach to diplomacy will only end in a stalemate. Nothing actually productive will come out of it.

The issue I'm seeing is that you have identified problems but are only willing to consider a single solution and no other options. I don't really see how you expect such inflexibility to receive a positive response.

[WraithKenny]

My comments aren't here anymore, because I wasted hours articulating the problems, only to remember no one here actually gives a shit about my time, and I'm only hurting myself by trying to contribute. Thumbs down isn't fucking friendly? Fuck you, you stupid piece of shit. Go fuck yourself, and fuck this project, and fuck all the maintainers. I've deleted all my patches and forks. I've deleted my comments. If I could fucking delete all the code that ended up in Wordpress, I'd fucking do that to.

[WraithKenny]

I'm going to leave that one post until someone else deleted it and bans me from this Repo, because I'm fucking right, and these passive aggressive pricks are the barrier to contributions, with their false fucking civility and fake politeness.

[noahtallen]

Though I know this conversation has mostly come to a close, I did want to answer a couple of questions that came up. I also still think it's important to consider monorepo solutions to some of the problems which could (in theory) be solved by a separate repository.

The test cases that run on this repository seem mainly Gutenberg-related. Which of the tests validate that wp-env is working correctly? Are those tests somehow tied to the Gutenberg code?

Since Gutenberg is a complex WordPress plugin, it relies heavily on the underlying WordPress environment. If the underlying WordPress environment breaks through a change in wp-env, tests in Gutenberg will fail. So you could consider each Gutenberg test also a test of wp-env. Gutenberg tests related to file uploads also test that the wp-env file system works with file uploads, for example. It's important for us to not make a change to wp-env which would cause a plugin to stop working with it. The Gutenberg test suite has the side effect of testing that. We know that wp-env works well in CI because it is working great in the Gutenberg CI suite.

Additionally, the lint checks will lint wp-env code, and the unit tests will run the wp-env unit tests. So wp-env gets a significant amount of test coverage "by accident," just because the wp-env code is used in CI and part of the monorepo!

I do think there are monorepo solutions to many of the other problems:

• Build times. Interestingly, wp-env doesn't have any build step. If you execute ./packages/env/bin/wp-env, it will run the local files directly in node, no build step. So I think local development is extremely easy for that reason.
• Dependencies. Yarn has a thing called focus workspaces, where only dependencies related to the package you want to develop are installed. I think npm has, in newer versions, a similar feature, so in theory that will help solve that problem.
• CI taking a long time. I don't think this is just a wp-env problem! Certainly everyone would love for CI to be blazing fast in Gutenberg :)

I also wonder if the issue with how quickly contributions are accepted is more related to the number of people maintaining wp-env? I don't have the time to focus on wp-env any more, and I often become a bottleneck when no one else is looking at new PRs to wp-env.

[talldan]

Agree with your points Noah.

I think it's time to close this issue given this is clearly not going to happen, but also as the conversation became toxic and aggressive.

I did start one new pull request to help improve things based on one of the (now deleted) comments - https://github.com/WordPress/gutenberg/pull/38122.

I'm happy to also work on other ways to improve the contributing experience. Lets focus on making individual issues/PRs though for those things.