Submitting Patches to Github with WordPress Playground

Today, I’d like to talk about a new step I added to the WordPress Playground Step Library that makes it easier to configure WordPress Playground in a way that you can easily submit Pull Requests to the Github repository where the project is hosted.

What is the Step Library? It is a tool that makes it easier to create a so called Blueprint for WordPress Playground that boots WordPress in your browser window according to your needs.

The specific step I introduced is called the githubTheme step. It will run a theme from a Github repository.

Additionally, and this is mostly following guidance from Nick Diego for his own Nautilus theme, by ticking a checkbox, it will configure Playground in a way that you can submit Pull Requests through playground (open this setup in the step library):

Screen Recording

So after creating the blueprint, there are a number of steps to take until you arrive at your PR. To show this better, I created a Screen Recording but below I also extracted some screenshots and commented them. This is the Pull Request created in the video, and here is also the playground link that the step library generated so that you can try it out yourself.

The screencast actually shows how I first missed the right button but then demonstrates that you can also update PRs.

Screenshots from the Recording

Here are some screenshots from the video (omitting my mistake):

First, you connect to your Github Account (I had already done this, so this just proceeds)
In the Site Editor, I can then change the color palette like this
Then I use the Create Block Theme plugin to save the changes to the theme
And press “Save Changes”
Choose to export the Pull Request to Github
And give some details before submitting it to Github
This is now the final Github Pull Request

How does it work?

It is amazing what WordPress Playground can do: it runs WordPress in your browser, so there is a virtual filesystem to which the Create Block Theme can write its file changes. The

Already in November 2023, Adam Zielinski published the GitHub Pull Request submission flow but only recently Nick Diego showed me how practical this is for theme developers. The only downside: it takes quite a lot to configure:

  1. You need a blueprint to run your theme from Github,
  2. Make sure that the Create Block Theme plugin is installed, and finally
  3. Configure a set of URL parameters for Playground to let it know where the PR should go, which directory to export etc.

The Step Library makes this more accessible by automatically setting those query parameters for you. It’s then also easy to add more steps, just try it out, using the above as a basis!

If you want to read a bit more about the Step Library, I recommend reading my previous post on it.

As of now, I wouldn’t call the flow simple: you need to be taught steps on how to submit changes. But when you know them, submitting a PR to a WordPress theme can be done without any server infrastructure! I think this is fascinating!

WordPress Playground Step Library

WordPress Playground is this fascinating tool that allows you to run WordPress without a server. It achieves this by running PHP in your browser by using WASM. It sounds cool, and it makes for numerous interesting demos, as its original creator Adam Zielinski showed at WordCamp Europe 2024: WordPress Playground – use WordPress without a server (recording, slides).

Having built Translate Live for WordPress.org–a way to translate plugins and themes without having to use a table UI–I have a bit of experience with having WordPress Playground do more complex things. But I also know that it be a bit difficult to get started with that.

Blueprints to start a Playground

So, as you can see with Translate Live, a WordPress Playground can be booted into configurations, and these configurations are (currently) called Blueprints. They are JSONs made of options and a list of steps. You can choose from a number of available steps like installPlugin to share a link with someone to try something in WordPress without having to set up hosting for that.

The available steps are somewhat basic but powerful. It can be abstract to think of what to do with them.

So, I had the idea that while the available steps of WordPress Playground are quite universal, we could build a library of “more meaningful” steps that do and “transpile” them to existing steps.

Build a Playground Blueprint with a Drag and Drop UI

Welcome to the WordPress Playground Step Library: Combining these steps with a click (or drag and drop) UI, it allows you do quickly create a WordPress Playground that does things you didn’t know you could easily do. Here is a screenshot:

So, for example, it could be useful when you share a WordPress Playground link to add some explanatory text, and what better to use than the infamous1 Admin Notice? But, how do you do it?

Turns out, you’d need a small mu-plugin. But with a custom step, it’s just a matter of adding that step:

So such a “custom blueprint” for playground would be this:

{
  "landingPage": "/",
  "steps": [
    {
      "step": "showAdminNotice",
      "vars": {
        "text": "Welcome to WordPress Playground!"
      }
    }
  ]
}

But careful. The above doesn’t run in Playground. There is no showAdminNotice step. But the Step Library automaticaly transpiles to a valid blueprint:

{
  "landingPage": "/wp-admin/",
  "login": true,
  "steps": [
    {
      "step": "mkdir",
      "path": "wordpress/wp-content/mu-plugins"
    },
    {
      "step": "writeFile",
      "path": "wordpress/wp-content/mu-plugins/0-mu.php",
      "data": "<?php add_action( 'admin_notices', function() { echo '<div class=\"notice notice-success is-dismissible\"><p>Welcome to WordPress Playground!</p></div>'; } ); ?>"
    }
  ]
}

So which one is easier to remember? :-) You can try this blueprint in WordPress Playground now! It will look like this:

WordPress showing an admin notice: Welcome to WordPress Playground!

I’ve made the Step Library so when you configure it, its URL reflects to your custom steps (this is the above in the Step Library) so that you can easily share them. If you wanted to share the actual running playground, share the URL of the “Launch in Playground” link.

The Playground link will start with https://playground.wordpress.net/, the Step Library link with https://akirk.github.io/playground-step-library/.

The Step Library is hosted on Github and you can contribute your own steps! Also happy to receive new issues with ideas of what steps might be useful to add. There also the Blueprints Gallery that showcases further uses of Playground and is also open to contributions!

So far, I have added these steps:

I’m curious if this tool can help you build a WordPress Playground, please tell me by commenting via Mastodon or ActivityPub, and spread the word about the tool!

Oh, and checkout the Awesome WordPress Playground link collection if you want to learn more about Playground or check out interesting applications! Happy playing!

  1. This is traditionally misused by plugins to prompt you to upgrade so that your wp-admin screen can get bloated with this. To the point where there is an Admin Notices Manager plugin that allows you to keep them under control. ↩︎