Promoting and supporting wp-now at WordCamp Europe

[danielbachhuber]

It would be really neat if some WordCamp Europe Contributor Day attendees were able to successfully use wp-now or the VS Code extension. Let's use this issue to strategize how we can achieve this. We can create sub-issues as we go, too.

cc @sejas @kozer @wojtekn @katinthehatsite @adamziel

Done is:

• We've tested against and prepared Quick Starts Guides for the Gutenberg and Learn teams.
• The VS Code Extension and wp-now codebase are updated to their latest versions.
• A dozen or more WCEU Contributor Day attendees are able to successfully use wp-now or the VS Code extension as a part of their Contributor Day experience.

[kozer]

I want to think more about it, and I'll update the thread.

Some ideas are:

• We can create some videos of before and after, using wp-env and wp-now to show them how they can handle different developer scenarios.

[adamziel]

I love this discussion!

Two largest obstacles are:

• git clone wordpress-develop – people don't know terminal, git, and the internet is terrible. Also, git is not shipped with VS Code – you need to have it installed in the first place.
• npm run dev – ditto but now they also need npm

Can we figure out a workflow that only involves wordpress-develop zipball?

As in, I download the latest trunk, which is already much smaller than what I get by default with git clone, and then I work in the src directory. Once my change is ready, I diff against the zipball version and submit that as a PR. I never install npm packages, composer deps, and I never run webpack. Unit tests? Lean on GitHub CI.

It is cumbersome, but teaching people about CLI, GIT, and NPM in a few hours is 10x more cumbersome.

[adamziel]

We can create some videos of before and after, using wp-env and wp-now to show them how they can handle different developer scenarios.

For the more advanced folks, that sounds great! We could reuse those videos in the docs.

[adamziel]

Oh – a "start contributing in 15 seconds" workflow is larger than WordCamp EU. It would be huge for WordPress as a whole.

[danielbachhuber]

a "start contributing in 15 seconds" workflow is larger than WordCamp EU. It would be huge for WordPress as a whole.

Building on this, one idea:

1. See which Make teams will be present on Contributor Day.
2. Document a "start contributing in 15 seconds" workflow for them (and make sure it works on a variety of platforms).
3. Socialize the workflow with the table lead prior to the event.
4. Offer them a "I need help" workflow (and potentially an escape hatch) if they run into issues during the event.

In the interest of not biting off more than we can chew, we may want to focus on 1-3 Make teams exclusively, and make sure we're successful with them first.

[adamziel]

Yup, sounds amazing. I'll be happy to chat with them once we can come up with such a workflow.

Offer them a "I need help" workflow (and potentially an escape hatch) if they run into issues during the event.

Do you mean "default to what they did a year ago" or something else?

---

Running wp-now on wordpress-develop/src shows this error message – that's a problem.

I wonder if the plugin could run npm install on its own without actually installing NPM 🤔

NPM is an npm package. Surely it exposes some API. We have a JavaScript runtime in VS Code. Maybe we can so somthing like require('npm').install(packageJson)?

[sejas]

Maybe we could add buttons to that default html page to let people run npm install with just one click.
And then another click to npm run dev.

[eliot-akira]

Can we figure out a workflow that only involves wordpress-develop zipball?
..never install npm packages, composer deps, and I never run webpack.

If the goal is to let people start developing without knowledge of Git, NPM, or Composer.. Perhaps one way to solve it is to prepare a zip download that already has all dependencies installed, including NPM modules, Composer modules, and wp-now. It would be a (possibly much) larger download, but all that needs to be downloaded anyway for local development. Instead of a multi-step preparation involving various CLI tools, it could be a single step with wp-now ready to go.

[adamziel]

@eliot-akira That would be fantastic, especially since we could just put it on a USB stick and not rely on the internet connection at all!

The problem is npm might choose to install different versions of the packages depending on your OS and CPU, so a mac M1 user would get different prebuilt binaries than a intel windows user than a linux user. Some libraries have a portable wasm version, some don't. It boils down to the specific WordPress dependency tree – if we're lucky, it's all JavaScript. If we're not lucky, there's plenty of node-gyp stuff. Perhaps there's a way to force installing a portable WebAssembly builds of things, though? If isn't, npm install is the next best thing.

Another issue is that we'd have to do it for every WordCamp since trunk continues moving forward. That's not that big of a deal, though. CI or GitHub actions could handle that. Actually that would be even better since new contributors could always download the prebuilt thing even outside of WordCamp, and not worry about git clone and npm install at all. The VS Code extension could even have a button for that.

[eliot-akira]

we could just put it on a USB stick and not rely on the internet connection at all

That sounds useful for people with unreliable Internet, e.g., while travelling, or in rural areas. One way to achieve this and still support native binaries, could be to prepare releases for every major OS/CPU combination: Linux/Windows/macOS on x64 and ARM.

---

..never install npm packages, composer deps, and I never run webpack.

Another approach could be for wp-now or the VS Code extension to include an abstraction layer that makes local development as simple as possible. One-click install for NPM modules, click here to start/stop webpack, etc. That way, ideally, a contributor can do everything in the editor and never need to open a terminal.

---

Document a "start contributing in 15 seconds" workflow

Given the time constraints, the shortest path may be to prepare a clear set of instructions: how to install everything, and what commands to run to get started. It certainly won't be "15 seconds" though. Git is probably already available on Linux, macOS, and Windows with WSL2. But Composer requires installing PHP, which can be complex and error prone.

and make sure it works on a variety of platforms

Docker seems like the most reliable cross-platform way to ensure a consistent local dev environment with all dependencies ready to go. But then we're back to wp-env.

If we can assume that everyone is running VS Code, it has built-in support for editing within containers. Maybe we could prepare something like vscode-wordpress.

Devcontainer scripts to develop Wordpress extensions or sites using VSCode remote containers.

It extends the wordpress docker image with xdebug, wpcli, composer, mysql, node, and most common sense linux utils like curl, zsh, bash, ssh, ag, ...

A leaner script could provide the minimum required setup: Git, Node/NPM, PHP, Composer, WP-CLI, and wp-now.

(EDIT: But then again, such a setup can run the dev scripts in wordpress-develop directly, so it wouldn't need wp-now. And all this is pretty much what wp-env does anyway, by generating Docker Compose files.)

[adamziel]

@eliot-akira These are all great ideas, thank you for sharing! This may end up going in the direction of USB sticks, clearer instructions, and better support for the proper tooling in the end. I'd still like to give the "everything included" approach a shot and see where it takes us. It may not work out, but it should be a good source for insights for this and other Playground-related issues.

But Composer requires installing PHP, which can be complex and error prone.

PHP.wasm from this repo works with Composer!

Using npm, the library, to install packages

I got require("npm") to work!

First, bad news. NPM removed the programmatic API and calling require("npm") actually fails with:

The programmatic API was removed in npm v8.0.

Now the good news. You can remove the exports section of npm's package.json file and call require('npm/lib/npm.js') like this:

require('npm/lib/npm.js');
const npm = new NPM();
npm.exec('install', ['express']);

This code actually installed express! Next step: bundle npm, the library, and run it in VS Code on a machine without node.js installed.

Edit: I got it to run in VS Code! I got blocked on another error (Tracker "idealTree" already exists) that I think could be solved, but perhaps we don't need to – see below

[adamziel]

Assumptions:

• Contributor day
• No USB sticks
• Okay internet connection

These are the options:

Basic: No Docker or npm, many limitations

1. Download wordpress/wordpress
2. Contribute PHP changes
3. Test with VS Code extension / wp-now
4. Create a patch. Either ask someone at the same table or there could be a "Create a patch" button in the VS Code extension

Upsides:

• Already works, no additional work required
• Quick to setup on Contributor Day
• The least possible number of downloads

Downsides:

• No contributing to JS and CSS
• No version control, patching could get icky

Intermediate: No docker + bundled npm

1. Clone wordpress-develop, the extension could have a button for that
2. Run npm tasks (install, dev, build) through npm bundled inside of the extension
3. Use git for patches

Upsides:

• Still easy to setup
• Mostly no limitations

Downsides:

• Difficult to create
• Maintenance burden (npm versions used in WordPress change over time, debugging npm errors won't be easy)
• Need to download everything

Full: Docker-based

• Clone wordpress-develop
• Install DevContainers for VS Code (thank you @eliot-akira!)
• Install Docker Desktop through DevContainers (yes! that's a thing!)
• Run a predefined Dockerfile through dev containers
• You're done. No need to use WordPress Playground VS Code extension.

Upsides:

• No need to use terminal, it's all GUI based
• No limitations at all, you have a full environment
• No maintenance on our end – it's completely unrelated to the WordPress Playground project.

Downsides:

• Lots of downloads
• No opportunity for WordPress Playground

[danielbachhuber]

I'd recommend focusing on 1-2 contributor groups first. It will be difficult to solve everyone's workflow in this first phase. Gutenberg seems like the obvious place to start, without much additional consideration.

[adamziel]

Yeah that's the conclusions I'm reaching too @danielbachhuber. We have two separate topics here:

1. Help new contributors using WordPress Playground
2. Create a "0 to ready in a few minutes" workflow for WordPress via the wordpress-develop repo

They may sound similar but are very distinct. Let's focus on 1 and defer to WordPress on 2.

[sejas]

Increasing the awareness that using GitHub Codespaces is another option to contribute without installing any other tool, directly from the browser.

wp-now-github-codespaces.mp4

[danielbachhuber]

@adamziel @sejas @kozer @wojtekn @katinthehatsite @adamwoodnz Getting https://github.com/WordPress/Learn running with wp-now has been a rocky experience (#39 (comment)), so I don't think it's possible to formally support it at WordCamp Europe Contributor Day.

Maybe y'all could focus on Gutenberg and the Themes table (Theme Review Team)? Here's the existing Theme Review Onboarding Guide.

[adamziel]

Gutenberg and Themes sound good @danielbachhuber

[adamziel]

Theme Review:

For a theme to be added to the Theme Directory, the theme must:

be GPL compatible.
be secure.
be free of PHP or JS notices/warnings/errors.
not be in conflict with plugins (e.g. prefixing).
be translation ready.
use WordPress functions, hooks, filters and libraries.
not do anything illegal, dishonest, or morally offensive.
These are the basics, but the list of requirements is much longer than that.

more info here

[danielbachhuber]

@sejas and I chatted today about the contributors guide he's working on.

Here's my suggested structure for it:

• Introduction - what it is, how it’s different, and why you might want to use it.
  • Mention both wp-now and VS Code Extension
  • Primarily best for JavaScript contributions (couple of known PHP limitations)
• Getting Started / Installing
  • Minimum requirements
• Contributing to Gutenberg
  • Create a Gutenberg PR Step By Step
  • Test a Gutenberg PR Step By Step
  • Test a Gutenberg PR with the web version of WordPress Playground
• Contributing to Themes
  • …
• Contributing to other Make projects
  • Not fully supported at this time, use at your own risk
• Known Limitations
  • Can’t run PHPUnit
  • Can’t set WP_DEBUG
• Getting Help and Contributing Back
  • WordPress Playground Table at Contributor Day
  • #meta-playground Slack channel
  • GitHub repo

With some additional thought, I think we should simply publish it as a Markdown document in this repo, and then Contributor Day team leads can point to it. Having a single document in a GitHub repo means: 1) we can improve upon it as the day goes on, and 2) folks will naturally get acquainted with where the code lives.

Also, prior to Contributor Day, we should test our Getting Started guide with a contribution to each team.

At Contributor Day, I'd suggest:

• We have one YOLO team member join each team table (Core Editor and Themes) to answer any questions (at least for first hour or so)
• We have one YOLO team member at the WordPress Playground table to help Adam (can be a morning rotation/afternoon rotation)

Generally, I expect we'll see these scenarios:

1. Contributor is able to get up and running without problems
2. Contributor tries to get up and running but runs into some system-level problem -> capture as a GitHub issue
3. Contributor gets up and running, uses it for a while, and then runs into some quirk or issue -> capture as a GitHub issue

I'd suggest prioritizing efforts in this order:

• Helping folks get started. If someone runs into a problem, create an issue with sufficient detail, reproduction steps, etc., and then move on to the next person (i.e. don't spend a bunch of time trying to fix their issue)
• Helping enable others' contributions to WordPress Playground and Playground Tools.
• Making your own contributions, bug fixes, etc.

cc @kozer @katinthehatsite @wojtekn and fyi @adamziel

[danielbachhuber]

@adamziel Do you think it'd make sense to solve this with an even more generic 'Using WordPress Playground at Contributor Day' document that lives in https://github.com/WordPress/wordpress-playground ? It could mention testing Gutenberg PRs with the web interface, the Translation Playground, etc., in addition to wp-now and the VS Code extension.

[adamziel]

@danielbachhuber yes! It could also include a guide to translating WordPress using Live Translations and testing themes using online Playground - cc @akirk

I’m worried about the windows issues and I’ll allocate some time to help debug them before wceu

[sejas]

Thank you all for your help and contribution!