From 81149dc32a1b5489b3dad8d9abec9b3fefd7db33 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Wed, 24 Apr 2024 18:27:36 +0200 Subject: [PATCH 01/17] Reorganize chapters and add Local Development chapter --- .../docs/site/docs/01-start-here/01-index.md | 4 +- packages/docs/site/docs/04-nodejs/01-index.md | 27 ------------- .../docs/05-local-development/01-index.md | 39 +++++++++++++++++++ .../02-vscode-extension.md | 18 +++++++++ .../05-local-development/03-php-wasm-node.md | 19 +++++++++ .../docs/05-local-development/_category_.json | 3 ++ .../09-contributor-day.md} | 0 packages/docs/site/docs/16-faq.md | 18 --------- .../site/docs/_fragments/_wp_now_overview.mdx | 9 ----- 9 files changed, 81 insertions(+), 56 deletions(-) delete mode 100644 packages/docs/site/docs/04-nodejs/01-index.md create mode 100644 packages/docs/site/docs/05-local-development/01-index.md create mode 100644 packages/docs/site/docs/05-local-development/02-vscode-extension.md create mode 100644 packages/docs/site/docs/05-local-development/03-php-wasm-node.md create mode 100644 packages/docs/site/docs/05-local-development/_category_.json rename packages/docs/site/docs/{14-contributor-day/01-index.md => 13-contributing/09-contributor-day.md} (100%) delete mode 100644 packages/docs/site/docs/16-faq.md delete mode 100644 packages/docs/site/docs/_fragments/_wp_now_overview.mdx diff --git a/packages/docs/site/docs/01-start-here/01-index.md b/packages/docs/site/docs/01-start-here/01-index.md index 47fb19c7a5..37f389ce2f 100644 --- a/packages/docs/site/docs/01-start-here/01-index.md +++ b/packages/docs/site/docs/01-start-here/01-index.md @@ -24,9 +24,9 @@ This site (Documentation) is where you will find all the information you need to - [Start using WordPress Playground](../02-start-using/01-index.md) in 5 minutes (and check out the [demo site](https://playground.wordpress.net/)) - [Build your first app](../03-build-an-app/01-index.md) with WordPress Playground -- Use Playground as a zero-setup [local development environment](../04-nodejs/01-index.md#start-a-zero-setup-dev-environment-via-vscode-extension) +- Use Playground as a zero-setup [local development environment](../05-local-development/02-vscode-extension.md) - Read about the [limitations](../12-limitations/01-index.md) -- [WordCamp Contributor Day](../14-contributor-day/01-index.md) +- [WordCamp Contributor Day](../13-contributing/09-contributor-day.md) ## Take a deep dive diff --git a/packages/docs/site/docs/04-nodejs/01-index.md b/packages/docs/site/docs/04-nodejs/01-index.md deleted file mode 100644 index 1704dbbdde..0000000000 --- a/packages/docs/site/docs/04-nodejs/01-index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Usage in Node.js -slug: /usage-in-node-js ---- - -# Using WordPress Playground in Node.js - -As a WebAssembly project, WordPress Playground can also be used in Node.js. Here's how you can do it: - -import TOCInline from '@theme/TOCInline'; - - - -## Start a zero-setup dev environment via VScode extension - -You can use the [VScode extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) to develop your plugin or theme locally without installing Apache or MySQL. - -The extension ships with a portable WebAssembly version of PHP and sets up WordPress to use SQLite. All you have to do is click the "Start WordPress Server" button in VScode: - -import Image from '@theme/IdealImage'; -import vsCodeScreenshot from '@site/static/img/start-wordpress-server.png'; - -
- -### Work directly with WebAssembly PHP for Node.js - -And if you need a low-level control over the underlying WebAssembly PHP build, take a look at the [`@php-wasm/node` package](https://npmjs.org/@php-wasm/node) which ships the PHP WebAssembly runtime. This package is at the core of all WordPress Playground tools for Node.js. diff --git a/packages/docs/site/docs/05-local-development/01-index.md b/packages/docs/site/docs/05-local-development/01-index.md new file mode 100644 index 0000000000..5f04853633 --- /dev/null +++ b/packages/docs/site/docs/05-local-development/01-index.md @@ -0,0 +1,39 @@ +--- +title: wp-now +--- + +[`@wp-now/wp-now`](https://www.npmjs.com/package/@wp-now/wp-now) is a CLI tool that allows you to quickly spin up a WordPress site with a single command. Similarly to the [VS Code extension](/05-local-development/02-vscode-extension.md), it uses a portable WebAssembly version of PHP and SQLite. No Docker, MySQL, or Apache required. + +## Launch wp-now in a plugin or theme directory + +Running wp-now is as simple as accessing your plugin or theme directory and starting wp-now. + +```bash +cd my-plugin-or-theme-directory +npx @wp-now/wp-now start +``` + +## Launch wp-now in the `wp-content` directory with options + +You can also start wp-now from any wp-content folder. In this example, we pass parameters to change the PHP and WordPress versions and apply a blueprint file. + +```bash +cd my-wordpress-folder/wp-content +npx @wp-now/wp-now start --wp=5.9 --php=7.4 --blueprint=path/to/blueprint-example.json +``` + +:::info **Documentation** + +`wp-now` is maintained in a different GitHub repository, [Playground Tools](https://github.com/WordPress/playground-tools/). You can find the latest documentation in the [dedicated README file](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md). + +::: + +## Install wp-now globally + +Alternatively, you can install `@wp-now/wp-now` globally to it from any directory: + +```bash +npm install -g @wp-now/wp-now +cd wordpress-plugin-or-theme +wp-now start +``` diff --git a/packages/docs/site/docs/05-local-development/02-vscode-extension.md b/packages/docs/site/docs/05-local-development/02-vscode-extension.md new file mode 100644 index 0000000000..89dd90ab8c --- /dev/null +++ b/packages/docs/site/docs/05-local-development/02-vscode-extension.md @@ -0,0 +1,18 @@ +--- +title: VS Code extension +--- + +Start a zero-setup development environment using the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground), and develop your plugin or theme locally without installing Apache or MySQL. + +:::info **Documentation** + +The VS Code extentions is maintained in a different GitHub repository, [Playground Tools](https://github.com/WordPress/playground-tools/). You can find the latest documentation in the [dedicated README file](https://github.com/WordPress/playground-tools/blob/trunk/packages/vscode-extension/README.md). + +::: + +The extension ships with a portable WebAssembly version of PHP and sets up WordPress to use SQLite. All you have to do is click the **Start WordPress Server** button in VS Code: + +import Image from '@theme/IdealImage'; +import vsCodeScreenshot from '@site/static/img/start-wordpress-server.png'; + +
diff --git a/packages/docs/site/docs/05-local-development/03-php-wasm-node.md b/packages/docs/site/docs/05-local-development/03-php-wasm-node.md new file mode 100644 index 0000000000..c0c8fb5eaf --- /dev/null +++ b/packages/docs/site/docs/05-local-development/03-php-wasm-node.md @@ -0,0 +1,19 @@ +--- +title: php-wasm/node +--- + +# Using WordPress Playground in Node.js + +As a WebAssembly project, WordPress Playground can also be used in Node.js. + +If you need low-level control over the underlying WebAssembly PHP build, take a look at the [`@php-wasm/node` package](https://npmjs.org/@php-wasm/node) which ships the PHP WebAssembly runtime. This package is at the core of all WordPress Playground tools for Node.js. + +:::info **API reference** + +Consult the [full list](/api/node) of Classes, Functions, Interfaces, Type Aliases. + +::: + +import PHPWASMNode from '@php-wasm/node/\README.md'; + + diff --git a/packages/docs/site/docs/05-local-development/_category_.json b/packages/docs/site/docs/05-local-development/_category_.json new file mode 100644 index 0000000000..2db6aaf32f --- /dev/null +++ b/packages/docs/site/docs/05-local-development/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Local Development" +} diff --git a/packages/docs/site/docs/14-contributor-day/01-index.md b/packages/docs/site/docs/13-contributing/09-contributor-day.md similarity index 100% rename from packages/docs/site/docs/14-contributor-day/01-index.md rename to packages/docs/site/docs/13-contributing/09-contributor-day.md diff --git a/packages/docs/site/docs/16-faq.md b/packages/docs/site/docs/16-faq.md deleted file mode 100644 index f226c4a917..0000000000 --- a/packages/docs/site/docs/16-faq.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: FAQ -slug: /faq ---- - -# FAQ - -## Wait, where is PHP running? - -In your browser! It is mindblowing, isn't it? There's a new technology called WebAssembly that makes it possible. You can learn more in [this article on web.dev](https://web.dev/wordpress-playground/). - -## Is WordPress Playground available in another language? - -Yes! Although it requires some work at the moment. You need to tell Playground to download and install the translation files and one way to do it is using [the Blueprints API](https://make.wordpress.org/polyglots/2023/05/08/translate-live-updates-to-the-translation-playground/). There is no step-by-step tutorial yet, but you can learn by reading the source of [Playground+Translations plugin](https://translate.wordpress.org/projects/wp-plugins/friends/dev/en-gb/default/playground/) [(GitHub link)](https://github.com/akirk/wp-glotpress-playground/blob/main/index.php). - -## Will WP-CLI be supported? - -Yes! Some commands already work if you include `wp-cli.phar` in the executed PHP code, and support for others is work in progress. The documentation will be progressively updated to reflect the progress. diff --git a/packages/docs/site/docs/_fragments/_wp_now_overview.mdx b/packages/docs/site/docs/_fragments/_wp_now_overview.mdx deleted file mode 100644 index 6f675d8925..0000000000 --- a/packages/docs/site/docs/_fragments/_wp_now_overview.mdx +++ /dev/null @@ -1,9 +0,0 @@ -`wp-now` is a CLI tool that allows you to quickly spin up a WordPress site with a single command. Similarly to the VS Code extension, it uses a portable WebAssembly version of PHP and SQLite. No Docker, MySQL, or Apache is required. - -To install `wp-now` directly from `npm`: - -```bash -npm install -g @wp-now/wp-now -cd wordpress-plugin-or-theme -wp-now start -``` From 2cd2f0e21cae2129d0465c8fb025e37cb46371f1 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Wed, 24 Apr 2024 18:28:22 +0200 Subject: [PATCH 02/17] Add dev mode script to test the documentation site --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index 8f438bef27..1d0048c315 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,7 @@ "build": "nx run-many --all --target=build", "build:website": "nx build playground-website", "build:docs": "nx build docs-site", + "dev:docs": "nx dev docs-site", "changelog": "bun ./packages/meta/bin/update-changelog.ts", "deploy:docs": "gh-pages -d dist/docs/build -t true", "dev": "nx dev playground-website", From 452c37bda6d8d8dfee737b7016d5862f04e28a51 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Fri, 26 Apr 2024 17:48:14 +0200 Subject: [PATCH 03/17] Rewrite Limitations --- .../docs/site/docs/12-limitations/01-index.md | 37 +++++++++++-------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/packages/docs/site/docs/12-limitations/01-index.md b/packages/docs/site/docs/12-limitations/01-index.md index 7106455620..d17d7fb74a 100644 --- a/packages/docs/site/docs/12-limitations/01-index.md +++ b/packages/docs/site/docs/12-limitations/01-index.md @@ -1,36 +1,41 @@ --- -title: Limitations slug: /limitations --- # Limitations -WordPress Playground has a few limitations that you should be aware of. +WordPress Playground is under active development and has some limitations you should keep in mind when running it and developing with it. -## If you are a user +You can track the status of these issues on the [Playground Project board](https://github.com/orgs/WordPress/projects/180). -import Limitations from '@site/docs/\_fragments/\_limitations_ui.md'; +## In the browser - +### Access the Plugins, Themes, Blocks, or Patterns directories -## If you are a developer +Playground [disables network connections](../09-blueprints-api/03-data-format.md#features) by default, blocking access to wp.org assets (themes, plugins, blocks, or patterns) in `wp-admin`. You can still upload zipped plugin and theme files from your device or enable the option via the [Query API](../08-query-api/01-index.md#available-options) or [Blueprints API](../09-blueprints-api/09-troubleshoot-and-debug-blueprints.md#review-common-gotchas). -### Iframe quirks +### Temporary by design -WordPress is rendered in an iframe, which makes it hard to correctly handle `target="_top"` in links. This means that clicking on `Click here` may reload the main browser tab. +As Playground [streams rather than serves](../01-start-here/02-overview.md#streamed-not-served) WordPress, all database changes and uploads will be gone when you refresh the page. To avoid losing your work, either [export your work](../02-start-using/01-index.md#save-your-site) before or enable storage in the browser/device via the [Query API](../08-query-api/01-index.md#available-options) or the UI. -Also, JavaScript popup windows originating in the iframe may not be displayed in certain cases. +## When developing with Playground -### Pthreads Support +### Iframe quirks -The WebAssembly version of PHP is built without pthreads support, which means you cannot use `pcntl_` functions like `pcntl_fork()` or `pcntl_exec()`. Most of the time, you don't need them, but there are a few WP-CLI commands and a few corner-cases in PHPUnit tests that use them. +Playground renders WordPress in an `iframe` so clicking links with `target="_top"` will reload the page you’re working on. +Also, JavaScript popups originating in the `iframe` may not always display. -You can track the progress of adding pthreads support at https://github.com/WordPress/wordpress-playground/issues/347. +### Run WordPress PHP functions -### XDebug Support +Playground supports running PHP code in Blueprints using the [`runPHP` step](../09-blueprints-api/05-steps.md#RunPHPStep). To run WordPress-specific PHP functions, you’d need to first require [wp-load.php](https://github.com/WordPress/WordPress/blob/master/wp-load.php): -XDebug is not supported in the WebAssembly version of PHP. You can track the progress of adding XDebug support at https://github.com/WordPress/wordpress-playground/issues/314. +```json +{ + "step": "runPHP", + "code": "" +} +``` -### Fibers +### Using WP-CLI -Fibers are a PHP 8.1+ feature that is currently unsupported in Playground. See https://github.com/WordPress/wordpress-playground/blob/9065025043209ce06c9540886567ca5bc0ccfb11/packages/php-wasm/compile/Dockerfile#L484-L493 for more information. +You can execute `wp-cli` commands via the Blueprints [`wp-cli`](../09-blueprints-api/05-steps.md#WPCLIStep) step. However, since Playground runs in the browser, it doesn't support the [full array](https://developer.wordpress.org/cli/commands/) of available commands. While there is no definite list of supported commands, experimenting in [the online demo](https://playground.wordpress.net/demos/wp-cli.html) will help you assess what's possible. From bd08aa21ead26e4f713a2f598bcbaca165bb87c4 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 00:33:14 +0200 Subject: [PATCH 04/17] Rewrite WordCamp Contributor Day --- .../13-contributing/09-contributor-day.md | 118 +++++++++--------- 1 file changed, 57 insertions(+), 61 deletions(-) diff --git a/packages/docs/site/docs/13-contributing/09-contributor-day.md b/packages/docs/site/docs/13-contributing/09-contributor-day.md index 637f875a26..9d3e9f38ea 100644 --- a/packages/docs/site/docs/13-contributing/09-contributor-day.md +++ b/packages/docs/site/docs/13-contributing/09-contributor-day.md @@ -5,112 +5,108 @@ slug: /wordcamp-contributor-day # WordCamp Contributor Day -The WordPress Playground VS Code extension and wp-now are tools that streamline the process of setting up a local WordPress environment. Both are powered by WordPress Playground, eliminating the need for other tools like Docker and MySQL. +The [WordPress Playground VS Code extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) and [wp-now](https://www.npmjs.com/package/@wp-now/wp-now) streamline the process of setting up a local WordPress environment. Both are powered by WordPress Playground—no Docker, MySQL, or Apache required. -Read on to see how you can use either for contributing to WordPress. Please note that they’re currently in an alpha state and not all Make teams are fully supported. +Keep reading to learn how to use these tools for [local development](../05-local-development/01-wp-now.md) when contributing to WordPress. Please note that the extension and the NPM package are under development, and not all [Make WordPress teams](https://make.wordpress.org/) are fully supported. ## Getting Started -If you're a visual learner – here's a step-by-step video for you! If you prefer reading at your own pace, you're welcome to skip over to the written instructions below. +If you’re a visual learner, here’s a step-by-step video tutorial. If you prefer reading at your own pace, skip to the written instructions below. - + -### VSCode Playground extension +### VS Code Playground extension -[Visual Studio Code Playground extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) offers a friendly user interface to a local WordPress environment. +The [Visual Studio Code Playground extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) is a friendly zero-setup development environment. -To get started, open your Visual Studio Code and navigate to the extensions tab. In the search bar, type 'WordPress playground' and click 'Install'. This will add a new icon on your sidebar. +1. Open VS Code and navigate to the **Extensions** tab (**View > Extensions**). +2. In the search bar, type _WordPress Playground_ and click **Install**. +3. To interact with Playground, click the new icon in the **Activity Bar** and hit the **Start WordPress Server** button. +4. A new tab will open in your browser within a few seconds. -## wp-now +### wp-now NPM package -### Minimum Requirements +`@wp-now/wp-now` is a CLI tool that allows you to quickly spin up a WordPress site with a single command. No Docker, MySQL, or Apache required. -To get started with wp-now, you need to have Node and npm installed on your system. You can follow this guide to install them: [Node and npm installation guide](https://nodejs.org/en/download/package-manager). We also recommend using nvm to easily change the node version: [nvm installation guide](https://github.com/nvm-sh/nvm#installing-and-updating). +#### Prerequisites -### Installing +`wp-now` requires Node.js and NPM. If you haven't yet, [download and install](https://nodejs.org/en/download) both before you begin. -You can globally install wp-now npm package in your machine, or if you prefer, you can run these commands directly from your browser using GitHub codespaces.: [https://www.npmjs.com/package/@wp-now/wp-now](https://www.npmjs.com/package/@wp-now/wp-now). +Depending on the Make WordPress team you're contributing to, you may need a different Node.js version than the one you have installed. You can use Node Version Manager (NVM) to quickly switch between versions. [Find the installation guide here](https://github.com/nvm-sh/nvm#installing-and-updating). -``` -npm install -g @wp-now/wp-now -``` - -### Running +#### Run wp-now -To start a new server, navigate to your WordPress plugin or theme directory and run the command wp-now start. This will start the server with the default PHP and WordPress versions. A new tab will open automatically in your browser. +You don't have to install `wp-now` on your device to use it. Navigate to your plugin or theme directory and start `wp-now` with the following commands: -``` -cd gutenberg -wp-now start +```bash +cd my-plugin-or-theme-directory +npx @wp-now/wp-now start ``` -You can stop wp-now by killing the process by pressing the keys `CTRL + C`. +## Ideas for contributors -To change the PHP or WordPress version, you can use the `--php` and `--wp` arguments. For example, to start a server with PHP 7.4 and WordPress 6.1, you can run: +### Create a Gutenberg Pull Request (PR) -``` -wp-now start --php 7.4 --wp 6.1 -``` - -## Contributing to Gutenberg - -### Create a Gutenberg PR Step By Step +1. Begin by creating a fork of the [Gutenberg repository](https://github.com/WordPress/gutenberg) in your GitHub account. +2. Then, clone the forked repository to download the files. +3. Install the necessary dependencies, and build the code in development mode. -Begin by creating a fork of the Gutenberg repository using your GitHub account. Once you've done that, clone your forked repository to your local machine to download the code. Following this, install the necessary dependencies and build the Gutenberg files. - -``` +```bash git clone git@github.com:WordPress/gutenberg.git cd gutenberg npm install npm run dev ``` -Ensure that wp-now is installed on your system. Then, open a new terminal window and start the WordPress server by executing the wp-now command. +:::info -``` +If you're unsure about the steps listed above, visit the official [Gutenberg Project Contributor Guide](https://developer.wordpress.org/block-editor/contributors/). Note that in this case, `wp-now` replaces `wp-env`. + +::: + +Open a new terminal terminal tab, navigate to the Gutenberg directory, and start WordPress using `wp-now`: + +```bash cd gutenberg -wp-now start +npx @wp-now/wp-now start ``` -Commit and push your changes to your forked repository on GitHub and create a new pull request on the Gutenberg repository. - -For more in detail information, check the block editor handbook: https://developer.wordpress.org/block-editor/contributors/code/getting-started-with-code-contribution/#getting-the-gutenberg-code +When you're ready, commit and push your changes to your forked repository on GitHub and open a Pull Request on the Gutenberg repository. -### Test a Gutenberg PR Step By Step +### Test a Gutenberg PR -To test a Gutenberg PR with wp-now, start by navigating to the PR on the Gutenberg repository. Once there, checkout the PR branch to switch your local environment to the version of the code that includes the proposed changes. After checking out the branch, pull the latest changes to ensure your local copy is up to date. Next, run npm install to ensure all dependencies are up to date. This step is crucial as it ensures that your testing environment matches the one in which the changes were made. Finally, test the changes in your local environment. This could involve running unit tests and manually testing features in a browser. +1. To test other Gutenberg PRs, checkout the branch associated with it. +2. Pull the latest changes to ensure your local copy is up to date. +3. Next, install the necessary dependencies, ensuring that your testing environment matches the latest changes. +4. Finally, build the code in development mode. -``` -# copy the branch-name from GitHub +```bash +# copy the branch-name from GitHub # git checkout branch-name git pull npm install npm run dev -# In a different terminal inside the gutenberg folder -wp-now start +# In a different terminal inside the Gutenberg directory * +npx @wp-now/wp-now start ``` -### Test a Gutenberg PR with the web version of WordPress Playground - -You can manually test a Gutenberg pull request directly from your browser. Given a pull request URL, https://github.com/WordPress/gutenberg/pull/51239, copy the ID (in this case, `51239`) and paste it at https://playground.wordpress.net/gutenberg.html. Use your specific pull request ID. Once you press "Go," your Pull Request will open in a new WordPress Playground where you can review the proposed changes! - -![Mermaid chart](https://github.com/WordPress/wordpress-playground/assets/779993/d4bc5a27-1401-4f35-bc68-2fad0ef699d5) - -## Translate WordPress Plugins using the WordPress Playground - -You can translate WordPress Plugins and Themes the traditional way in the table view at https://translate.wordpress.org/, or you can load the plugin to be translated and use Inline Translation to do so. Find the `Translate Live` link on the top right of the translation view for this. See [this blog post for more context](https://make.wordpress.org/polyglots/2023/05/08/translate-live-updates-to-the-translation-playground/). +#### Test a Gutenberg PR with Playground in the browser -## Contributing to other Make projects +You don't need a local development environment to test Gutenberg PRs—use Playground to do it directly in the browser. -At this time, contributing to other Make projects is not fully supported at this time. +1. Copy the ID of the PR you'd like to test (pick one from the [list of open Pull Requests](https://github.com/WordPress/gutenberg/pulls)). +2. Open Playground's [Gutenberg PR Previewer](https://playground.wordpress.net/gutenberg.html), and paste the ID you copied. +3. Once you click **Go**, Playground will verify the PR is valid, and open a new tab with the relevant PR, allowing you to review the proposed changes. -## Known Limitations +## Translate WordPress Plugins with Playground in the browser -wp-now is in alpha version. Check out the known issues [https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md#known-issues](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md#known-issues). +You can translate supported WordPress Plugins by loading the plugin you want to translate and use Inline Translation. If the plugin developers have added the option, you'll find the **Translate Live** link on the top right toolbar of the translation view. You can read more about this exciting new option on [this Polyglots' blog post](https://make.wordpress.org/polyglots/2023/05/08/translate-live-updates-to-the-translation-playground/). -## Getting Help and Contributing to WordPress Playground +## Get help and contribute to WordPress Playground -If you encounter any issues when running your project with 'wp-now' or the VSCode Playground extension, don't hesitate to reach out to the Playground table or ask in the #meta-playground Slack channel. Someone will be around to assist you during the day. +Have a question or an idea for a new feature? Found a bug? Something's not working as expected? We're here to help: -If you come across a bug or if you have an idea for a potential feature, we encourage you to share your input. You can create an issue on our GitHub repository at [https://github.com/WordPress/playground-tools](https://github.com/WordPress/playground-tools). Alternatively, you can share your thoughts in the ‘#meta-playground’ channel on Slack. +- During Contributor Day, you can reach out to us at the **Playground table**. +- Open an issue on the [WordPress Playground GitHub repository](https://github.com/WordPress/wordpress-playground). +- Share your feedback on the [**#meta-playground** Slack channel](https://wordpress.slack.com/archives/C04EWKGDJ0K). From 7b5c68fb7f34ce5b0e7bf96fad01dcc10980ef53 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 13:01:37 +0200 Subject: [PATCH 05/17] Rewrite Documentation contributions --- .../docs/13-contributing/20-documentation.md | 70 ++++++------------- 1 file changed, 21 insertions(+), 49 deletions(-) diff --git a/packages/docs/site/docs/13-contributing/20-documentation.md b/packages/docs/site/docs/13-contributing/20-documentation.md index 4e35a144d1..509ed7089a 100644 --- a/packages/docs/site/docs/13-contributing/20-documentation.md +++ b/packages/docs/site/docs/13-contributing/20-documentation.md @@ -1,71 +1,43 @@ -# Contributing Documentation +# Documentation contributions -WordPress Playground is documented by volunteers and we welcome your contributions. +[WordPress Playground's documentation site](https://wordpress.github.io/wordpress-playground) is maintained by volunteers like you, who'd love your help. -The [documentation tracking issue](https://github.com/WordPress/wordpress-playground/issues/772) contains a list of all documentation-related issues. It’s a good starting point to see what’s missing and what’s already there. - -Anything that you were missing when exploring Playground for the first time is a great addition to the documentation, even if it requires a fundamental change in how the documentation speaks to the user. +All [documentation-related topics](https://github.com/WordPress/wordpress-playground/labels/%5BType%5D%20Documentation) are labeled `documentation`. Browse the list of open issues to find one you'd like to work on. Alternatively, if you believe something is missing from the current documentation, open an issue to discuss your suggestion. ## How can I contribute? -### I am not familiar with Markdown - -If you are not familiar with Markdown, you can contribute by [opening an issue in the project repository](https://github.com/WordPress/wordpress-playground/issues/new) and describing what you would like to see added or changed. - -You could even write the content in the issue description and the project contributors will take care of the rest. - -### I am familiar with Markdown - -If you are familiar with [Markdown](https://www.markdownguide.org/), you can directly propose changes and new documentation pages by submitting a Pull Request. If you're not familiar with Pull Requests, read the [Collaborating with pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) guide first. - -The existing documentation lives in the GitHub repository as Markdown files: +You can contribute by [opening an issue in the project repository](https://github.com/WordPress/wordpress-playground/issues/new) and describing what you'd like to add or change. -https://github.com/WordPress/wordpress-playground/tree/trunk/packages/docs/site/docs +If you feel up to it, write the content in the issue description, and the project contributors will take care of the rest. -Then, the documentation site is published here: +### I'm familiar with markdown and GitHub -https://wordpress.github.io/wordpress-playground +If you are familiar with markdown, you can propose changes and new documentation pages by submitting a Pull Request. -Some pages are written in [MDX](https://mdxjs.com/), which is Markdown with JSX. If you are not familiar with MDX, don't worry at all – you can still contribute to these pages by editing just the Markdown part. +The documentation is stored in Playground's GitHub repository, [under `/packages/docs/site/docs`](https://github.com/WordPress/wordpress-playground/tree/trunk/packages/docs/site/docs). -### Your first Pull Request +## Edit in the browser -#### An easy way to start - -Here's an easy way to start your first Pull Request: - -1. Go to https://github.com/WordPress/wordpress-playground/tree/trunk/packages/docs/site/docs -2. Find the page you'd like to edit or a directory where you'd like to add a new page -3. Click the "Add Files" button to add a new file, or click on an existing file and then click the pencil icon to edit it -4. GitHub will ask you to fork the repository and create a new branch for your changes – do that -5. An editor will open where you can make your changes -6. When you're done, click the Commit Changes button and start a Pull Request +1. Find the page you'd like to edit or the directory of the chapter you'd like to add a new page to. +2. Click the **Add Files** button to add a new file, or click on an existing file and then click the pencil icon to edit it. +3. GitHub will ask you to fork the repository and create a new branch with your changes. +4. An editor will open where you can make the changes. +5. When you're done, click the **Commit Changes** button and submit a Pull Request. That's it! You've just contributed to the WordPress Playground documentation. -The upside of this approach is that you don't need to clone the repository, set up a local development environment, or run any commands. You can edit the documentation directly in your browser. +This approach means you don't need to clone the repository, set up a local development environment, or run any commands. -The downside is that you won't be able to preview your changes on the documentation site. Previewing is not critical and you can be a successful contributor without it, but if you'd still like to see your changes before submitting a Pull Request, follow the instructions below. +The downside is that you won't be able to preview your changes. Keep reading to learn how to review your changes before submitting a Pull Request. -#### A more difficult way with a preview +### Local preview -If you'd like to a preview of your changes, you'll need to clone the repository and run the following commands: +Clone the repository and navigate to the directory on your device. Now run the following commands: ```bash -npm install -g nx npm install -nx dev docs-site +npm run build:docs +npm run dev:docs ``` -This will start a local server where you can preview your changes. From there, you can edit the documentation files -in your code editor and see the changes in real-time. - -## What to contribute? - -See the [documentation tracking issue](https://github.com/WordPress/wordpress-playground/issues/772) for an up to date list of specific tasks and documentation pages that need to be written. - -## General guidelines - -- Document any limitations you run into at https://wordpress.github.io/wordpress-playground/limitations/ -- The documentation structure needs brushing up, you are welcome to move pages around and propose new structures -- Use simple language and avoid jargon +The documentation site opens in a new browser tab and refreshes automatically with each change. Continue to edit the relevant file in your code editor and test the changes in real-time. From fdc25a44db532478dc12de36a2877c51f0f1ea89 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 18:21:28 +0200 Subject: [PATCH 06/17] Rewrite Code contributions --- .../docs/site/docs/13-contributing/02-code.md | 68 ++++++++++++------- 1 file changed, 42 insertions(+), 26 deletions(-) diff --git a/packages/docs/site/docs/13-contributing/02-code.md b/packages/docs/site/docs/13-contributing/02-code.md index ef13d96fa9..e2cd03f2fd 100644 --- a/packages/docs/site/docs/13-contributing/02-code.md +++ b/packages/docs/site/docs/13-contributing/02-code.md @@ -1,60 +1,76 @@ --- sidebar_position: 1 -title: Code Contributions --- -# Code Contributions +# Code contributions -The WordPress Playground project uses GitHub for managing code and tracking issues. The main repository is at: [https://github.com/WordPress/wordpress-playground](https://github.com/WordPress/wordpress-playground). +Like all WordPress projects, Playground uses GitHub to manage code and track issues. The repository is at [https://github.com/WordPress/wordpress-playground](https://github.com/WordPress/wordpress-playground). -To contribute Pull Requests, you'll need to fork the Playground repository and clone it to your local machine. You can then create a branch, make changes, and submit a pull request. +Browse [the list of open issues](https://github.com/wordpress/wordpress-playground/issues) to find what to work on. The [`Good First Issue`](https://github.com/wordpress/wordpress-playground/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) label is a recommended starting point for first-time contributors. -Once you have a fork, you can clone it as follows – just replace `WordPress/wordpress-playground` with your GitHub username and repository name: +Be sure to review the following resources before you begin: + +- [Coding principles](./03-coding-standards.md) +- [Architecture](../11-architecture/01-index.md) +- [Vision and Philosophy](https://github.com/WordPress/wordpress-playground/issues/472) +- [WordPress Playground Roadmap](https://github.com/WordPress/wordpress-playground/issues/525) + +## Contribute Pull Requests + +[Fork the Playground repository](https://github.com/WordPress/wordpress-playground/fork) and clone it to your local machine. To do that, copy and paste these commands into your terminal: ```bash -git clone -b trunk --single-branch --depth 1 git@github.com:WordPress/wordpress-playground.git +git clone -b trunk --single-branch --depth 1 + +# replace `YOUR-GITHUB-USERNAME` with your GitHub username: +git@github.com:YOUR-GITHUB-USERNAME/wordpress-playground.git cd wordpress-playground -nvm use # You'll need Node 16 or later npm install +``` + +Create a branch, make changes, and test it locally by running the following command: + +```bash npm run dev ``` -That's it, WordPress Playground is now running on your machine and you're ready to contribute! +Playground will open in a new browser tab and refresh automatically with each change. -Browse [the issues list](https://github.com/wordpress/wordpress-playground/issues) to find issues to work on. The [good first issue](https://github.com/wordpress/wordpress-playground/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) labels are good starting points. +When your'e ready, commit the changes and submit a Pull Request. -Be sure to also review the following resources: +:::info Formatting -- [Coding Standards](./03-coding-standards.md) -- [Packages and projects](./04-packages-and-projects.md) -- [Vision and Philosophy](https://github.com/WordPress/wordpress-playground/issues/472) -- [Roadmap](https://github.com/WordPress/wordpress-playground/issues/525) +We handle code formatting and linting automatically. Relax, type away, and let the machines do the work. + +::: -## HTTPS setup +### Running a local Multisite -Some Playground features, like multisite, require a local test domain running via HTTPS. +WordPress Multisite has a few [restrictions when run locally](https://developer.wordpress.org/advanced-administration/multisite/prepare-network/#restrictions). If you plan to test a Multisite network using Playground's `enableMultisite` step, make sure you either change `wp-now`'s default port or set a local test domain running via HTTPS. -One way to get it set up is with [Laravel Valet](https://laravel.com/docs/10.x/valet). +To change `wp-now`'s default port to the one supported by WordPress Multisite, run it using the `--port=80` flag: + +```bash +npx @wp-now/wp-now start --port=80 +``` -Once your Valet is installed, run: +There are a few ways to set up a local test domain, including editing your `hosts` file. If you're unsure how to do that, we suggest installing [Laravel Valet](https://laravel.com/docs/11.x/valet) and then running the following command: ```bash valet proxy playground.test http://localhost:5400 --secure ``` -Your dev server is now available via https://playground.test. +Your dev server is now available on https://playground.test. ## Debugging -### Debugging with VSCode and Chrome +### Use VS Code and Chrome -Playground can be debugged using VSCode and Chrome. To do so, follow these steps: +If you're using VS Code and have Chrome installed, you can debug Playground in the code editor: -- Open the project in VSCode -- Go to the _Run and Debug_ view (Ctrl+Shift+D) -- Select _Launch Chrome_ from the dropdown -- Click the green play button to start the debugger (F5) +- Open the project folder in VS Code. +- Select Run > Start Debugging from the main menu or press `F5`/`fn`+`F5`. ### Debugging PHP -In the web version of Playground, you can see PHP errors in the browser console. PHP errors are also logged after every PHP request using `console.debug` in the browser console. +Playground logs PHP errors in the browser console after every PHP request. From 7f25d313c1e03eee5c1c2cd32393832e70ee3605 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 18:22:06 +0200 Subject: [PATCH 07/17] Rewrite Code principles --- .../13-contributing/03-coding-standards.md | 75 +++++++------------ 1 file changed, 27 insertions(+), 48 deletions(-) diff --git a/packages/docs/site/docs/13-contributing/03-coding-standards.md b/packages/docs/site/docs/13-contributing/03-coding-standards.md index 4442765e79..66f72df238 100644 --- a/packages/docs/site/docs/13-contributing/03-coding-standards.md +++ b/packages/docs/site/docs/13-contributing/03-coding-standards.md @@ -1,73 +1,52 @@ --- sidebar_position: 1 -title: Coding standards --- -# Coding standards +# Coding principles ## Error messages -A good error message tells the reader exactly what to do next. This matters especially for errors thrown by Playground public APIs. Any ambiguity in those prompts the developers to open issues in the repo. However, the error message could provide the reader will all the answers. +A good error message tells the user what to do next. Any ambiguity in errors thrown by Playground public APIs will prompt the developers to open issues. -Consider a network error – can we infer what type of error was that and provide a dedicated message outlining the next steps +Consider a network error, for example—can we infer the type of error and display a relevant message summarizing the next steps? -- If it's a network error – say your internet connection twitched and reloading the page should fix the issue. -- If it's 404 – say file couldn't be found. -- If it's 403 – say it's probably a private resource. -- If it's a CORS error, provide a paragraph or two of text to explain it's a browser security thing, provide a link that explains what's CORS, say they need to move their file somewhere else, e.g. GitHub / raw.githubusercontent.com, link out to a resource explaining setting up CORS headers on their existing servers. +- **Network error**: "Your internet connection twitched. Try to reload the page. +- **404**: "Could not find the file". +- **403**: "The server blocked access to the file". +- **CORS**: clarify it's a browser security feature and add a link to a detailed explanation (on MDN or another reliable source). Suggest the user move their file somewhere else, like raw.githubusercontent.com, and link to a resource explaining how to set up CORS headers on their servers. -## Formatting - -Formatting is handled automatically by the relevant tools and verified by CI. Relax, sit back, and let the machines do the work. +We handle code formatting and linting automatically. Relax, type away, and let the machines do the work. ## Public API -Playground aims to keep the lowest possible API area. +Playground aims to keep the narrowest possible API scope. -Public APIs are easy to add and hard to remove. It only takes one PR to add a new API, but it may take a thousand to remove it – especially if was already consumed in other projects. +Public APIs are easy to add and hard to remove. It only takes one PR to introduce a new API, but it may take a thousand to remove it, especially if other projects have already consumed it. -Don't expose anything that is not needed. If you don't need to expose a function, don't. If you don't need to expose a class, don't. If you don't need to expose a constant, don't. +- Don't expose unnecessary function, class, constant, or other components. ## Blueprints -Blueprints are the main way to interact with the WordPress Playground. They are JSON files that describe a set of steps to perform. The Playground will execute these steps in order. - -### Batteries - -Blueprint steps are meant to be small and focused – like Unix tools. They should do one thing and do it well. - -When it comes to building new steps: - -- It is best not to build it at all -- If you must build it, try refactoring an existing step first -- If you cannot do that, make sure the new step opens up an entirely new feature that doesn't do anything that can be achieved with existing steps - -### Composability - -Blueprint Steps are meant to be composable. This means that you can run them many times over and still get sensible results. - -**Don't:** - -- Assume your step won't be run more than once. -- Assume your step will be run in a specific order. -- Modify PHP files to define constants. - -**Do:** +Blueprints are the primary way to interact with Playground. These JSON files describe a set of steps that Playground executes in order. -- Add unit tests that run your step multiple times. -- Store constants in virtual JSON files. +### Guidelines -### Ease of use +Blueprint steps should be **concise and focused**. They should do one thing and do it well. -Blueprints are meant to be easy to use and require the minimal amount of effort on the consumer side. +- If you need to create a new step, try refactoring an existing one first. +- If that's not enough, ensure the new step delivers a new capability. Don't replicate the functionality of existing steps. -**Don't:** +Blueprint steps should be **idempotent**, so you can run them multiple times and get similar results. -- Require arguments that can be made optional. -- Require complex arguments when simple ones will do. For example, don't require a plugin path when plugin slug will do. +- Assume the step would run more than once. +- Assume it would run in a specific order. +- Add unit tests to verify that. +- Define constants in virtual JSON files—don't modify PHP files. -**Do:** +Blueprints should be **intuitive and straightforward**. -- Provide a TypeScript type for the Blueprint. JSON Schema is generated from it. -- Provide a function to handle a blueprint step. Accept argument of the type you defined in the previous step. -- Provide usage example in the doc string. It is automatically reflected in the docs. +- Don't require arguments that can be optional. +- Use plain argument. For example, `slug` instead of `path`. +- Define a TypeScript type for the Blueprint. That's how Playground generates its JSON schema. +- Write a function to handle a Blueprint step. Accept the argument of the type you defined. +- Provide a usage example in the doc string. It's automatically reflected in the docs. From 7f7da49195563280a36e435e0b07f1e1b1da8add Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 18:24:15 +0200 Subject: [PATCH 08/17] Misc: links, paths, typos, and minor fixes --- .../docs/site/docs/06-playground-apis/02-api-concepts.md | 2 +- .../09-browser-tab-orchestrates-execution.md | 4 ++-- .../docs/11-architecture/10-browser-iframe-rendering.md | 4 ++-- .../docs/11-architecture/18-host-your-own-playground.md | 7 +++---- 4 files changed, 8 insertions(+), 9 deletions(-) diff --git a/packages/docs/site/docs/06-playground-apis/02-api-concepts.md b/packages/docs/site/docs/06-playground-apis/02-api-concepts.md index 8796c5bce6..95e8b0e754 100644 --- a/packages/docs/site/docs/06-playground-apis/02-api-concepts.md +++ b/packages/docs/site/docs/06-playground-apis/02-api-concepts.md @@ -6,7 +6,7 @@ title: Concepts WordPress Playground in the browser is all about links and iframes. Regardless of which API you choose, you will use it in one of the following ways: -### Link to the Playground site +## Link to the Playground site You can customize WordPress Playground by modifying the https://playground.wordpress.net/ link. You can, for example, create a post, request a specific plugin, or run any PHP code. diff --git a/packages/docs/site/docs/11-architecture/09-browser-tab-orchestrates-execution.md b/packages/docs/site/docs/11-architecture/09-browser-tab-orchestrates-execution.md index e57de0fb96..2f1940cd4f 100644 --- a/packages/docs/site/docs/11-architecture/09-browser-tab-orchestrates-execution.md +++ b/packages/docs/site/docs/11-architecture/09-browser-tab-orchestrates-execution.md @@ -8,7 +8,7 @@ Keep this point in mind as you read through the rest of the docs. At this point Here's what a boot sequence for a minimal app looks like: -![The boot sequence](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/docs/site/static/img/boot-sequence.png) +![The boot sequence](../../static/img/boot-sequence.png) The main app initiates the Iframe, the Service Worker, and the Worker Thread. Note how the main app doesn't use the PHP stack directly – it's all handled in the Worker Thread. @@ -66,7 +66,7 @@ Keep reading to learn how all these pieces fit together. Here's what happens whenever the iframe issues a same-domain request: -![The data flow](https://raw.githubusercontent.com/wordpress/wordpress-playground/trunk/pages/data-flow.png) +![The data flow](../../static/img/data-flow.png) A step-by-step breakdown: diff --git a/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md b/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md index 397082a8c9..b22e1795fc 100644 --- a/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md +++ b/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md @@ -20,5 +20,5 @@ This time, clicking the link the browser to load `page.php` **inside the iframe* ## Iframes caveats -- `target="_top"` isn't handled yet. This means that clicking on `Click here` will reload the main browser tab. -- JavaScript popup windows originating in the iframe may not work correctly yet. +- `target="_top"` isn't handled yet, so clicking links with `target="_top"` will reload the page you’re working on. +- JavaScript popup originating in the `iframe` may not always display. diff --git a/packages/docs/site/docs/11-architecture/18-host-your-own-playground.md b/packages/docs/site/docs/11-architecture/18-host-your-own-playground.md index 2dd5614dd7..8439bdb4b9 100644 --- a/packages/docs/site/docs/11-architecture/18-host-your-own-playground.md +++ b/packages/docs/site/docs/11-architecture/18-host-your-own-playground.md @@ -58,6 +58,7 @@ git clone -b trunk --single-branch --depth 1 git@github.com:WordPress/wordpress- ``` Enter the `wordpress-playground` directory. + ```sh cd wordpress-playground ``` @@ -98,11 +99,9 @@ For these to work, you need a server environment with Apache and PHP installed. As an alternative to Apache, here is an example of using NGINX to serve the Playground. -:::info Refer to source files - -This example may go out of date. It is recommended to refer to the source files. +:::info Refer to the source file -- [packages/playground/wordpress/public/.htaccess](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/wordpress/public/.htaccess) +The example may be outdated. Please check [the source file](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/remote/.htaccess) for the latest version. ::: From 180f04877a93ef84c900bb232ff345506115cd46 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 18:42:56 +0200 Subject: [PATCH 09/17] Rewrite Start contributing --- .../site/docs/13-contributing/01-index.md | 28 +++++++++++-------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/packages/docs/site/docs/13-contributing/01-index.md b/packages/docs/site/docs/13-contributing/01-index.md index b0a3a0076d..73a588dd5b 100644 --- a/packages/docs/site/docs/13-contributing/01-index.md +++ b/packages/docs/site/docs/13-contributing/01-index.md @@ -1,21 +1,25 @@ ---- -title: Start Contributing ---- +# Start contributing -# Start Contributing - -WordPress Playground is an open-source project and welcomes all contributors from code to design, and from documentation to triage. Don't worry, you don't need to know WebAssembly to contribute! +WordPress Playground is an open-source project that welcomes all contributors—from code to design, documentation to triage. ## How can I contribute? - Code? See the [developer section](./02-code.md). - Documentation? See the [documentation section](./20-documentation.md). -- Reporting bugs? Open an [issue](https://github.com/WordPress/wordpress-playground/issues/new) in the repository. -- Triage – see the [triage section](./05-triage.md). -- Ideas, designs or anything else? Open a [GitHub discussion](https://github.com/WordPress/wordpress-playground/discussions) and let's talk! +- Reporting bugs? Open an [issue](https://github.com/WordPress/wordpress-playground/issues/new) in the GitHub repository. +- Ideas, designs, or anything else? Open a [GitHub discussion](https://github.com/WordPress/wordpress-playground/discussions), and let's talk! ## Guidelines -- As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](https://make.wordpress.org/handbook/community-code-of-conduct/). -- Contributors should review the [coding standards](./03-coding-standards.md). -- You maintain copyright over any contribution you make. By submitting a pull request you agree to release that code under [WordPress Playground License](https://github.com/WordPress/wordpress-playground/blob/HEAD/LICENSE). +- As with all WordPress projects, we want to ensure a welcoming and respectful environment for everyone. Please read our community's [Code of Conduct](https://make.wordpress.org/handbook/community-code-of-conduct/) to learn more. +- Code contributors should review the [coding principles](./03-coding-standards.md). +- You maintain copyright over any contribution you make. By submitting a Pull Request, you agree to release that code under [WordPress Playground License](https://github.com/WordPress/wordpress-playground?tab=GPL-2.0-1-ov-file#readme). + +# Triaging issues + +Want to help sort through open issues and resolve potential bugs? Here's how: + +1. Review the [list of open issues](https://github.com/WordPress/wordpress-playground/issues?q=is%3Aopen+is%3Aissue) and find the ones that you can help with. +2. Read through the description and comments. +3. If it's a bug you can reproduce, add a descriptive comment or a potential fix. +4. Otherwise, add a comment with any additional information that may be helpful. From 91dab59107aad8a20b59c37556d010aa5938daf1 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 19:09:35 +0200 Subject: [PATCH 10/17] Add Crash reports to the Architecture chapter --- .../docs/11-architecture/10-browser-iframe-rendering.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md b/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md index b22e1795fc..656b0bd38d 100644 --- a/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md +++ b/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md @@ -18,6 +18,14 @@ Now, consider an iframe with the same link in it: This time, clicking the link the browser to load `page.php` **inside the iframe**. The top-level index.html where the PHP application runs remains unaffected. This is why iframes are a crucial part of the `@php-wasm/web` setup. +:::info Crash reports +Playground doesn't collect crash reports automatically. Instead, it prompts users to submit a crash report when an instance fails to run in the browser. + +The report includes a log, a description, and the URL, and users can modify it before submitting. + +The [Logger API](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/website/public/logger.php) handles it from there. This simple REST API validates the data and sends it to the **Making WordPress** [#playground-logs Slack channel](https://wordpress.slack.com/archives/C06Q5DCKZ3L). +::: + ## Iframes caveats - `target="_top"` isn't handled yet, so clicking links with `target="_top"` will reload the page you’re working on. From 992411d3ddfe799b885bc738ab5dd2e7af3f84ff Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 19:46:56 +0200 Subject: [PATCH 11/17] Add tooling (NX and Lerna) to Architecture overview --- .../site/docs/11-architecture/01-index.md | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/packages/docs/site/docs/11-architecture/01-index.md b/packages/docs/site/docs/11-architecture/01-index.md index 35f2a5d26e..bfd1d0fa8f 100644 --- a/packages/docs/site/docs/11-architecture/01-index.md +++ b/packages/docs/site/docs/11-architecture/01-index.md @@ -1,4 +1,4 @@ -# Architecture Overview +# Architecture overview WordPress Playground consists of the following high-level components: @@ -9,3 +9,22 @@ WordPress Playground consists of the following high-level components: - [Public API](../06-playground-apis/01-index.md) Visit each section to learn more about the specific parts of the architecture. + +## Tooling + +### NX: building packages and projects + +WordPress Playground uses [NX](https://nx.dev/), a build system designed for monorepos. + +The dependencies between Playground packages and projects [are too complex](https://github.com/WordPress/wordpress-playground/pull/151) for a bundler like Webpack, and NX handles this complexity much better: +![Dependency graph](@site/static/img/dependencies.png) + +To learn more, head over to the [NX developer docs](https://nx.dev/getting-started/intro). + +### Lerna: publishing packages and projects + +WordPress Playground includes several NPM packages, a VS Code extension, WordPress plugins, a web app, and other GitHub releases, all managed across two monorepos. + +We use [Lerna](https://lerna.js.org) to build, manage, and publish all JavaScript/TypeScript packages. Lerna handles everything simultaneously: it increments the version number, sets a new tag, and publishes the modified packages to `npm`. + +The published packages share the same version number, so when updating a single package, Lerna bumps the version number of all dependent packages. From da3c723808fcb7e156fba67c1c71dd3900e68341 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 21:36:48 +0200 Subject: [PATCH 12/17] Add links to the Tools repo (for contributors) --- .../site/docs/11-architecture/01-index.md | 2 +- .../site/docs/13-contributing/01-index.md | 4 +- .../docs/site/docs/13-contributing/02-code.md | 8 +++- .../13-contributing/09-contributor-day.md | 39 +++++++++---------- 4 files changed, 29 insertions(+), 24 deletions(-) diff --git a/packages/docs/site/docs/11-architecture/01-index.md b/packages/docs/site/docs/11-architecture/01-index.md index bfd1d0fa8f..f64e70afbc 100644 --- a/packages/docs/site/docs/11-architecture/01-index.md +++ b/packages/docs/site/docs/11-architecture/01-index.md @@ -23,7 +23,7 @@ To learn more, head over to the [NX developer docs](https://nx.dev/getting-start ### Lerna: publishing packages and projects -WordPress Playground includes several NPM packages, a VS Code extension, WordPress plugins, a web app, and other GitHub releases, all managed across two monorepos. +WordPress Playground includes several NPM packages, a VS Code extension, WordPress plugins, a web app, and other GitHub releases, all managed across two monorepos: the main [wordpress-playground](https://github.com/WordPress/wordpress-playground) and [Playground Tools](https://github.com/WordPress/playground-tools/). We use [Lerna](https://lerna.js.org) to build, manage, and publish all JavaScript/TypeScript packages. Lerna handles everything simultaneously: it increments the version number, sets a new tag, and publishes the modified packages to `npm`. diff --git a/packages/docs/site/docs/13-contributing/01-index.md b/packages/docs/site/docs/13-contributing/01-index.md index 73a588dd5b..ae7aeb6af2 100644 --- a/packages/docs/site/docs/13-contributing/01-index.md +++ b/packages/docs/site/docs/13-contributing/01-index.md @@ -6,7 +6,7 @@ WordPress Playground is an open-source project that welcomes all contributors— - Code? See the [developer section](./02-code.md). - Documentation? See the [documentation section](./20-documentation.md). -- Reporting bugs? Open an [issue](https://github.com/WordPress/wordpress-playground/issues/new) in the GitHub repository. +- Reporting bugs? Open a [new issue](https://github.com/WordPress/wordpress-playground/issues/new) in the main GitHub repository, or in [Playground Tools](https://github.com/WordPress/playground-tools/issues/new). - Ideas, designs, or anything else? Open a [GitHub discussion](https://github.com/WordPress/wordpress-playground/discussions), and let's talk! ## Guidelines @@ -19,7 +19,7 @@ WordPress Playground is an open-source project that welcomes all contributors— Want to help sort through open issues and resolve potential bugs? Here's how: -1. Review the [list of open issues](https://github.com/WordPress/wordpress-playground/issues?q=is%3Aopen+is%3Aissue) and find the ones that you can help with. +1. Review the [list of open issues](https://github.com/WordPress/wordpress-playground/issues?q=is%3Aopen+is%3Aissue) and find the ones that you can help with. Same goes for the [Plaground Tools repository](https://github.com/WordPress/playground-tools/issues?q=is%3Aopen+is%3Aissue). 2. Read through the description and comments. 3. If it's a bug you can reproduce, add a descriptive comment or a potential fix. 4. Otherwise, add a comment with any additional information that may be helpful. diff --git a/packages/docs/site/docs/13-contributing/02-code.md b/packages/docs/site/docs/13-contributing/02-code.md index e2cd03f2fd..0078efe483 100644 --- a/packages/docs/site/docs/13-contributing/02-code.md +++ b/packages/docs/site/docs/13-contributing/02-code.md @@ -4,7 +4,13 @@ sidebar_position: 1 # Code contributions -Like all WordPress projects, Playground uses GitHub to manage code and track issues. The repository is at [https://github.com/WordPress/wordpress-playground](https://github.com/WordPress/wordpress-playground). +Like all WordPress projects, Playground uses GitHub to manage code and track issues. The main repository is at [https://github.com/WordPress/wordpress-playground](https://github.com/WordPress/wordpress-playground) and the Playground Tools repository is at [https://github.com/WordPress/playground-tools/](https://github.com/WordPress/playground-tools/). + +:::info Contribute to Playground Tools + +This guide includes links to the main repository, but all the steps and options apply for both. If you're interested in the plugins or local development tools—start there. + +::: Browse [the list of open issues](https://github.com/wordpress/wordpress-playground/issues) to find what to work on. The [`Good First Issue`](https://github.com/wordpress/wordpress-playground/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) label is a recommended starting point for first-time contributors. diff --git a/packages/docs/site/docs/13-contributing/09-contributor-day.md b/packages/docs/site/docs/13-contributing/09-contributor-day.md index 9d3e9f38ea..1c58ad06f6 100644 --- a/packages/docs/site/docs/13-contributing/09-contributor-day.md +++ b/packages/docs/site/docs/13-contributing/09-contributor-day.md @@ -1,11 +1,10 @@ --- -title: WordCamp Contributor Day slug: /wordcamp-contributor-day --- # WordCamp Contributor Day -The [WordPress Playground VS Code extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) and [wp-now](https://www.npmjs.com/package/@wp-now/wp-now) streamline the process of setting up a local WordPress environment. Both are powered by WordPress Playground—no Docker, MySQL, or Apache required. +The [WordPress Playground VS Code extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) and [wp-now](https://www.npmjs.com/package/@wp-now/wp-now) streamline the process of setting up a local WordPress environment. WordPress Playground powers both—no Docker, MySQL, or Apache required. Keep reading to learn how to use these tools for [local development](../05-local-development/01-wp-now.md) when contributing to WordPress. Please note that the extension and the NPM package are under development, and not all [Make WordPress teams](https://make.wordpress.org/) are fully supported. @@ -22,21 +21,21 @@ The [Visual Studio Code Playground extension](https://marketplace.visualstudio.c 1. Open VS Code and navigate to the **Extensions** tab (**View > Extensions**). 2. In the search bar, type _WordPress Playground_ and click **Install**. 3. To interact with Playground, click the new icon in the **Activity Bar** and hit the **Start WordPress Server** button. -4. A new tab will open in your browser within a few seconds. +4. A new tab will open in your browser within seconds. ### wp-now NPM package -`@wp-now/wp-now` is a CLI tool that allows you to quickly spin up a WordPress site with a single command. No Docker, MySQL, or Apache required. +`@wp-now/wp-now` is a CLI tool that allows you to spin up a WordPress site with a single command. No Docker, MySQL, or Apache are required. #### Prerequisites -`wp-now` requires Node.js and NPM. If you haven't yet, [download and install](https://nodejs.org/en/download) both before you begin. +`wp-now` requires Node.js and NPM. If you haven’t yet, [download and install](https://nodejs.org/en/download) both before you begin. -Depending on the Make WordPress team you're contributing to, you may need a different Node.js version than the one you have installed. You can use Node Version Manager (NVM) to quickly switch between versions. [Find the installation guide here](https://github.com/nvm-sh/nvm#installing-and-updating). +Depending on the Make WordPress team you contribute to, you may need a different Node.js version than the one you have installed. You can use Node Version Manager (NVM) to switch between versions. [Find the installation guide here](https://github.com/nvm-sh/nvm#installing-and-updating). #### Run wp-now -You don't have to install `wp-now` on your device to use it. Navigate to your plugin or theme directory and start `wp-now` with the following commands: +You don’t have to install `wp-now` on your device to use it. Navigate to your plugin or theme directory and start `wp-now` with the following commands: ```bash cd my-plugin-or-theme-directory @@ -47,9 +46,9 @@ npx @wp-now/wp-now start ### Create a Gutenberg Pull Request (PR) -1. Begin by creating a fork of the [Gutenberg repository](https://github.com/WordPress/gutenberg) in your GitHub account. +1. Fork the [Gutenberg repository](https://github.com/WordPress/gutenberg) in your GitHub account. 2. Then, clone the forked repository to download the files. -3. Install the necessary dependencies, and build the code in development mode. +3. Install the necessary dependencies and build the code in development mode. ```bash git clone git@github.com:WordPress/gutenberg.git @@ -60,7 +59,7 @@ npm run dev :::info -If you're unsure about the steps listed above, visit the official [Gutenberg Project Contributor Guide](https://developer.wordpress.org/block-editor/contributors/). Note that in this case, `wp-now` replaces `wp-env`. +If you’re unsure about the steps listed above, visit the official [Gutenberg Project Contributor Guide](https://developer.wordpress.org/block-editor/contributors/). Note that in this case, `wp-now` replaces `wp-env`. ::: @@ -71,13 +70,13 @@ cd gutenberg npx @wp-now/wp-now start ``` -When you're ready, commit and push your changes to your forked repository on GitHub and open a Pull Request on the Gutenberg repository. +When you’re ready, commit and push your changes to your forked repository on GitHub and open a Pull Request on the Gutenberg repository. ### Test a Gutenberg PR 1. To test other Gutenberg PRs, checkout the branch associated with it. 2. Pull the latest changes to ensure your local copy is up to date. -3. Next, install the necessary dependencies, ensuring that your testing environment matches the latest changes. +3. Next, install the necessary dependencies, ensuring your testing environment matches the latest changes. 4. Finally, build the code in development mode. ```bash @@ -93,20 +92,20 @@ npx @wp-now/wp-now start #### Test a Gutenberg PR with Playground in the browser -You don't need a local development environment to test Gutenberg PRs—use Playground to do it directly in the browser. +You don’t need a local development environment to test Gutenberg PRs—use Playground to do it directly in the browser. -1. Copy the ID of the PR you'd like to test (pick one from the [list of open Pull Requests](https://github.com/WordPress/gutenberg/pulls)). -2. Open Playground's [Gutenberg PR Previewer](https://playground.wordpress.net/gutenberg.html), and paste the ID you copied. -3. Once you click **Go**, Playground will verify the PR is valid, and open a new tab with the relevant PR, allowing you to review the proposed changes. +1. Copy the ID of the PR you’d like to test (pick one from the [list of open Pull Requests](https://github.com/WordPress/gutenberg/pulls)). +2. Open Playground’s [Gutenberg PR Previewer](https://playground.wordpress.net/gutenberg.html) and paste the ID you copied. +3. Once you click **Go**, Playground will verify the PR is valid and open a new tab with the relevant PR, allowing you to review the proposed changes. ## Translate WordPress Plugins with Playground in the browser -You can translate supported WordPress Plugins by loading the plugin you want to translate and use Inline Translation. If the plugin developers have added the option, you'll find the **Translate Live** link on the top right toolbar of the translation view. You can read more about this exciting new option on [this Polyglots' blog post](https://make.wordpress.org/polyglots/2023/05/08/translate-live-updates-to-the-translation-playground/). +You can translate supported WordPress Plugins by loading the plugin you want to translate and use Inline Translation. If the plugin developers have added the option, you'll find the **Translate Live** link on the top right toolbar of the translation view. You can read more about this exciting new option on [this Polyglots blog post](https://make.wordpress.org/polyglots/2023/05/08/translate-live-updates-to-the-translation-playground/). ## Get help and contribute to WordPress Playground -Have a question or an idea for a new feature? Found a bug? Something's not working as expected? We're here to help: +Have a question or an idea for a new feature? Found a bug? Something’s not working as expected? We’re here to help: -- During Contributor Day, you can reach out to us at the **Playground table**. -- Open an issue on the [WordPress Playground GitHub repository](https://github.com/WordPress/wordpress-playground). +- During Contributor Day, you can reach us at the **Playground table**. +- Open an issue on the [WordPress Playground GitHub repository](https://github.com/WordPress/wordpress-playground/issues/new). If your focus is the VS Code extension, NPM package, or the plugins, open an issue on the [Plaground Tools repository](https://github.com/WordPress/playground-tools/issues/new). - Share your feedback on the [**#meta-playground** Slack channel](https://wordpress.slack.com/archives/C04EWKGDJ0K). From 90a27ef2f80d1a66c9d574961c718fa95976b95b Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 21:42:59 +0200 Subject: [PATCH 13/17] Polish Local Development --- .../docs/05-local-development/01-wp-now.md | 41 +++++++++++++++++++ .../02-vscode-extension.md | 8 ++-- .../05-local-development/03-php-wasm-node.md | 4 +- 3 files changed, 46 insertions(+), 7 deletions(-) create mode 100644 packages/docs/site/docs/05-local-development/01-wp-now.md diff --git a/packages/docs/site/docs/05-local-development/01-wp-now.md b/packages/docs/site/docs/05-local-development/01-wp-now.md new file mode 100644 index 0000000000..79416bb646 --- /dev/null +++ b/packages/docs/site/docs/05-local-development/01-wp-now.md @@ -0,0 +1,41 @@ +--- +slug: wp-now +--- + +# wp-now NPM package + +[`@wp-now/wp-now`](https://www.npmjs.com/package/@wp-now/wp-now) is a CLI tool to spin up a WordPress site with a single command. Similarly to the [VS Code extension](/05-local-development/02-vscode-extension.md), it uses a portable WebAssembly version of PHP and SQLite. No Docker, MySQL, or Apache are required. + +## Launch wp-now in a plugin or theme directory + +Navigate to your plugin or theme directory and start `wp-now` with the following commands: + +```bash +cd my-plugin-or-theme-directory +npx @wp-now/wp-now start +``` + +## Launch wp-now in the `wp-content` directory with options + +You can also start `wp-now` from any `wp-content` folder. The following example passes parameters for changing the PHP and WordPress versions and loading a blueprint file. + +```bash +cd my-wordpress-folder/wp-content +npx @wp-now/wp-now start --wp=6.4 --php=8.0 --blueprint=path/to/blueprint.json +``` + +:::info **Documentation** + +`wp-now` is maintained in a different GitHub repository, [Playground Tools](https://github.com/WordPress/playground-tools/). You can find the latest documentation in the [dedicated README file](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md). + +::: + +## Install wp-now globally + +Alternatively, you can install `@wp-now/wp-now` globally to load it from any directory: + +```bash +npm install -g @wp-now/wp-now +cd my-plugin-or-theme-directory +wp-now start +``` diff --git a/packages/docs/site/docs/05-local-development/02-vscode-extension.md b/packages/docs/site/docs/05-local-development/02-vscode-extension.md index 89dd90ab8c..6de86fa23d 100644 --- a/packages/docs/site/docs/05-local-development/02-vscode-extension.md +++ b/packages/docs/site/docs/05-local-development/02-vscode-extension.md @@ -1,16 +1,14 @@ ---- -title: VS Code extension ---- +# VS Code extension Start a zero-setup development environment using the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground), and develop your plugin or theme locally without installing Apache or MySQL. :::info **Documentation** -The VS Code extentions is maintained in a different GitHub repository, [Playground Tools](https://github.com/WordPress/playground-tools/). You can find the latest documentation in the [dedicated README file](https://github.com/WordPress/playground-tools/blob/trunk/packages/vscode-extension/README.md). +The VS Code extension is maintained in a different GitHub repository, [Playground Tools](https://github.com/WordPress/playground-tools/). You can find the latest documentation in the [dedicated README file](https://github.com/WordPress/playground-tools/blob/trunk/packages/vscode-extension/README.md). ::: -The extension ships with a portable WebAssembly version of PHP and sets up WordPress to use SQLite. All you have to do is click the **Start WordPress Server** button in VS Code: +The extension ships with a portable WebAssembly version of PHP and sets up WordPress to use SQLite. Once installed, all you have to do is click the **Start WordPress Server** button in VS Code: import Image from '@theme/IdealImage'; import vsCodeScreenshot from '@site/static/img/start-wordpress-server.png'; diff --git a/packages/docs/site/docs/05-local-development/03-php-wasm-node.md b/packages/docs/site/docs/05-local-development/03-php-wasm-node.md index c0c8fb5eaf..220283c56c 100644 --- a/packages/docs/site/docs/05-local-development/03-php-wasm-node.md +++ b/packages/docs/site/docs/05-local-development/03-php-wasm-node.md @@ -4,13 +4,13 @@ title: php-wasm/node # Using WordPress Playground in Node.js -As a WebAssembly project, WordPress Playground can also be used in Node.js. +As a WebAssembly project, you can also use WordPress Playground in Node.js. If you need low-level control over the underlying WebAssembly PHP build, take a look at the [`@php-wasm/node` package](https://npmjs.org/@php-wasm/node) which ships the PHP WebAssembly runtime. This package is at the core of all WordPress Playground tools for Node.js. :::info **API reference** -Consult the [full list](/api/node) of Classes, Functions, Interfaces, Type Aliases. +Consult the [complete list](/api/node) of Classes, Functions, Interfaces, and Type Aliases. ::: From feeb42cc7dc8ee745abcc8d65eb3b17417392e1b Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 21:49:11 +0200 Subject: [PATCH 14/17] Minor copy improvements --- .../11-architecture/10-browser-iframe-rendering.md | 10 +++++----- .../docs/site/docs/11-architecture/15-wordpress.md | 8 ++------ 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md b/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md index 656b0bd38d..085b1f3f6b 100644 --- a/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md +++ b/packages/docs/site/docs/11-architecture/10-browser-iframe-rendering.md @@ -1,6 +1,6 @@ # Iframe-based rendering -All the PHPRequestHandler responses must be rendered in an iframe to avoid reloading the page. Remember, the entire setup only lives as long as the main `index.html`. We want to avoid reloading the main app at all cost. +To avoid page reloads, all the `PHPRequestHandler` responses must be rendered in an iframe. Remember, the entire setup only lives as long as the main `index.html`. We want to avoid reloading the main app at all costs. In our app example above, `index.php` renders the following HTML: @@ -8,7 +8,7 @@ In our app example above, `index.php` renders the following HTML: Go to page.php ``` -Imagine our `index.html` rendered it in a `
` instead of an ` ``` -This time, clicking the link the browser to load `page.php` **inside the iframe**. The top-level index.html where the PHP application runs remains unaffected. This is why iframes are a crucial part of the `@php-wasm/web` setup. +This time, click the link in the browser to load `page.php` **inside the iframe**. The top-level `index.html`, where the PHP application runs, remains unaffected. That's why iframes are crucial for the `@php-wasm/web` setup. :::info Crash reports Playground doesn't collect crash reports automatically. Instead, it prompts users to submit a crash report when an instance fails to run in the browser. -The report includes a log, a description, and the URL, and users can modify it before submitting. +The report includes a log, description, and a URL, and users can modify it before submitting it. The [Logger API](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/website/public/logger.php) handles it from there. This simple REST API validates the data and sends it to the **Making WordPress** [#playground-logs Slack channel](https://wordpress.slack.com/archives/C06Q5DCKZ3L). ::: @@ -29,4 +29,4 @@ The [Logger API](https://github.com/WordPress/wordpress-playground/blob/trunk/pa ## Iframes caveats - `target="_top"` isn't handled yet, so clicking links with `target="_top"` will reload the page you’re working on. -- JavaScript popup originating in the `iframe` may not always display. +- JavaScript popups originating in the `iframe` may not always display. diff --git a/packages/docs/site/docs/11-architecture/15-wordpress.md b/packages/docs/site/docs/11-architecture/15-wordpress.md index 1e00265c5b..7646354f0a 100644 --- a/packages/docs/site/docs/11-architecture/15-wordpress.md +++ b/packages/docs/site/docs/11-architecture/15-wordpress.md @@ -1,14 +1,10 @@ ---- -title: WordPress support ---- - # WordPress support WordPress, as a PHP application, can run on PHP WebAssembly. However, there are a few caveats. ## SQLite -First, WordPress requires MySQL. However, there isn't a WebAssembly version of MySQL you could run in the browser. WordPress Playground therefore ships PHP with the [native SQLite driver](https://www.php.net/manual/en/ref.pdo-sqlite.php) and leans on SQLite. +First, WordPress requires MySQL. However, there isn't a WebAssembly version of MySQL you could run in the browser. WordPress Playground, therefore, ships PHP with the [native SQLite driver](https://www.php.net/manual/en/ref.pdo-sqlite.php) and leans on SQLite. But how can WordPress run on a different database? @@ -16,7 +12,7 @@ Behind the scenes, the official [SQLite Database Integration](https://github.com ## WordPress in the browser -WordPress Playground ships a [bundled WordPress](./06-wasm-php-data-dependencies.md) that you can use in the browser. It's optimized for size and the installation wizard is already completed for you. +WordPress Playground ships a [bundled WordPress](./06-wasm-php-data-dependencies.md) that you can use in the browser. It's optimized for size, and the installation wizard is run for you. ## WordPress in Node.js From b03af399f44038f992f7ec00963308d2aa1757df Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Tue, 30 Apr 2024 21:49:49 +0200 Subject: [PATCH 15/17] Delete redundant pages --- .../docs/05-local-development/01-index.md | 39 ------ .../04-packages-and-projects.md | 112 ------------------ .../site/docs/13-contributing/05-triage.md | 15 --- .../docs/13-contributing/06-publishing.md | 41 ------- .../docs/13-contributing/07-crash-reports.md | 21 ---- .../site/docs/_fragments/_limitations_ui.md | 13 -- 6 files changed, 241 deletions(-) delete mode 100644 packages/docs/site/docs/05-local-development/01-index.md delete mode 100644 packages/docs/site/docs/13-contributing/04-packages-and-projects.md delete mode 100644 packages/docs/site/docs/13-contributing/05-triage.md delete mode 100644 packages/docs/site/docs/13-contributing/06-publishing.md delete mode 100644 packages/docs/site/docs/13-contributing/07-crash-reports.md delete mode 100644 packages/docs/site/docs/_fragments/_limitations_ui.md diff --git a/packages/docs/site/docs/05-local-development/01-index.md b/packages/docs/site/docs/05-local-development/01-index.md deleted file mode 100644 index 5f04853633..0000000000 --- a/packages/docs/site/docs/05-local-development/01-index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: wp-now ---- - -[`@wp-now/wp-now`](https://www.npmjs.com/package/@wp-now/wp-now) is a CLI tool that allows you to quickly spin up a WordPress site with a single command. Similarly to the [VS Code extension](/05-local-development/02-vscode-extension.md), it uses a portable WebAssembly version of PHP and SQLite. No Docker, MySQL, or Apache required. - -## Launch wp-now in a plugin or theme directory - -Running wp-now is as simple as accessing your plugin or theme directory and starting wp-now. - -```bash -cd my-plugin-or-theme-directory -npx @wp-now/wp-now start -``` - -## Launch wp-now in the `wp-content` directory with options - -You can also start wp-now from any wp-content folder. In this example, we pass parameters to change the PHP and WordPress versions and apply a blueprint file. - -```bash -cd my-wordpress-folder/wp-content -npx @wp-now/wp-now start --wp=5.9 --php=7.4 --blueprint=path/to/blueprint-example.json -``` - -:::info **Documentation** - -`wp-now` is maintained in a different GitHub repository, [Playground Tools](https://github.com/WordPress/playground-tools/). You can find the latest documentation in the [dedicated README file](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md). - -::: - -## Install wp-now globally - -Alternatively, you can install `@wp-now/wp-now` globally to it from any directory: - -```bash -npm install -g @wp-now/wp-now -cd wordpress-plugin-or-theme -wp-now start -``` diff --git a/packages/docs/site/docs/13-contributing/04-packages-and-projects.md b/packages/docs/site/docs/13-contributing/04-packages-and-projects.md deleted file mode 100644 index 79d38bc733..0000000000 --- a/packages/docs/site/docs/13-contributing/04-packages-and-projects.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -sidebar_position: 1 -title: NX – Packages and Projects ---- - -# NX: Packages and Projects - -WordPress Playground uses a tool called [nx](https://nx.dev/) to manage the repository. - -Why? - -The dependencies between Playground packages [are too complex](https://github.com/WordPress/wordpress-playground/pull/151) to manage with a bundler like webpack. Nx is the right tool for the job. Just look at this dependency graph: - -![Dependency graph](@site/static/img/dependencies.png) - -## Getting started with nx - -Start by reviewing the [Nx documentation](https://nx.dev/getting-started/intro). It's a good idea to install the Nx VS Code extension – it makes many common tasks easier. - -## Projects - -Nx uses the term "project" which is different from an npm "package". A project can be an npm package, a VS Code plugin, a web app that isn't published on npm, or even a directory with nothing more than a Dockerfile and a project.json file. - -## Tasks - -Every project needs a set of tasks so it can be built, tested, type-checked and so on. Tasks are stored in `project.json` files. Learn more about [tasks in nx documentation](https://nx.dev/core-features/run-tasks). - -## Add a new project / package - -Nx uses generators to create new packages. There are generators for Node.js libraries, web apps, angular apps, and more. - -For example, here's how you can create a new project containing a Node.js app: - -```bash -nx g @nrwl/node:application -``` - -Nx will then ask you many questions about the project. For example, it will ask you to choose a build tool. You can answer them in the terminal, or you can use the VS Code extension to answer them in a GUI – the latter is much easier. - -### Which tools to choose? - -In the Playground repository, we use the following tools: - -- TypeScript for type-checking -- Vite or esbuild for building both web apps and node.js apps -- Vitest for testing - -### After you create a new project - -Follow this checklist: - -- Add a new `workspaces` in the top-level `package.json` file if needed. Otherwise TypeScript won't work correctly and Lerna won't pick up your package for publishing. -- Add a `typecheck` task to the `project.json` file in the new project. You can copy it from another project in this repo. -- Run `nx typecheck ` to make sure TypeScript is set up correctly. -- If the project needs to ship both ESM and CJS builds, add a `test:esmcjs` task to the `project.json` and add it to the `dependsOn` list of the `test` task. This way the CI will continuously verify whether your double build works. The alternative is to find out when a disappointed extender files an issue. -- Add the `package-json` task to the build pipeline. See the details below. - -### Package.json - -Do not add any `dependencies` or `devDependencies` into the `package.json` file of the new project. WordPress Playground keeps track of all dependencies in the top-level `package.json` file and computes the one used by each project automatically using a custom NX executor. The process goes like this: - -1. Bundle the project into the `dist` directory, just copy the package.json as is -2. Add correct dependencies using the `@wp-playground/nx-extensions:package-json` executor - -Here's how you should configure the chain of build tasks in your `project.json`: - -```json -{ - "build": { - "executor": "nx:noop", - "dependsOn": ["build:package-json"] - }, - "build:package-json": { - "executor": "@wp-playground/nx-extensions:package-json", - "options": { - "tsConfig": "packages/php-wasm/node/tsconfig.lib.json", - "outputPath": "dist/packages/php-wasm/node", - "buildTarget": "php-wasm-node:build:bundle:production" - }, - "dependsOn": ["build:bundle"] - }, - "build:bundle": { - "//": "... your bundle task ..." - } -} -``` - -## Move a project to a different directory - -Use the [@nx/workspace:move](https://nx.dev/packages/workspace/generators/move) generator: - -```bash -nx g @nx/workspace:move --projectName= --destination= -``` - -Or use the VS Code extension – again, that's much easier than remembering all the commands. - -## Rename a project - -Same as above. - -## Delete a project - -Use the [@nx/workspace:remove](https://nx.dev/packages/workspace/generators/remove) generator: - -```bash -nx g @nx/workspace:remove --projectName= -``` - -## Publish a project on npm - -See the [publishing](./06-publishing.md) guide. diff --git a/packages/docs/site/docs/13-contributing/05-triage.md b/packages/docs/site/docs/13-contributing/05-triage.md deleted file mode 100644 index e32d79e048..0000000000 --- a/packages/docs/site/docs/13-contributing/05-triage.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_position: 1 -title: Triage Contributions ---- - -# Triaging issues - -You may help sort through WordPress Playground issues and determine their priority. Here's how: - -1. Go to the [WordPress Playground](https://github.com/WordPress/wordpress-playground/issues) repo on GitHub. -2. Click on the "Issues" tab to view the list of open issues. -3. Review the list of issues and look for ones that you can help with. -4. Once you've found an issue that you want to help with, read through the description and any comments to get a better understanding of the problem. -5. If you're able to reproduce the issue, add a comment to the issue with steps to reproduce it. This will help the developers to better understand the problem and come up with a solution. -6. If you're not able to reproduce the issue, add a comment to the issue with any additional information that you think might be helpful. This will help the developers to better understand the problem and come up with a solution. diff --git a/packages/docs/site/docs/13-contributing/06-publishing.md b/packages/docs/site/docs/13-contributing/06-publishing.md deleted file mode 100644 index e43cbc9442..0000000000 --- a/packages/docs/site/docs/13-contributing/06-publishing.md +++ /dev/null @@ -1,41 +0,0 @@ -# Publishing Packages, Releases, and More - -WordPress Playground has many types of artifacts that are published. - -NPM packages, GitHub releases, and playground.wordpress.net website are published by project maintainers through GitHub Actions. - -Below you'll find more details about parts of that process. - -## NPM packages - -WordPress Playground is a monorepo and uses Lerna for publishing npm packages. - -The publishing process is facilitated by Lerna, and includes automatically incrementing the version number, creating a new tag, and publishing all modified packages to npm simultaneously. - -Notably, all published packages share the same version number. All packages use the same version number. If you update a single package, Lerna will automatically bump the version number for all dependent packages. - -Each package identifies a distinct organization in its `package.json` file. To publish WordPress Playground packages, you need access to the following npm organizations: - -- `@wp-playground` -- `@php-wasm` - -To initiate the publishing process for the all the modified packages, execute the following commands: - -```bash -npm login # this is required only once and it will store the credentials in ~/.npmrc file. -npm run release -``` - -### After publishing - -To verify the publishing process went correctly: - -1. Please verify https://translate.wordpress.org/projects/wp-plugins/contact-form-7/dev/de/default/playground/ loads as expected. If it doesn't load, something broke. - -### When publishing packages goes wrong - -Internet connections drop, APIs stop responding, and GitHub rules are nasty. Stuff happens. If the publishing process fails, you may need to bump the version again and force a publish. To do so, execute the following command: - -```bash -npm run release -- --force-publish -``` diff --git a/packages/docs/site/docs/13-contributing/07-crash-reports.md b/packages/docs/site/docs/13-contributing/07-crash-reports.md deleted file mode 100644 index 89e8420ea7..0000000000 --- a/packages/docs/site/docs/13-contributing/07-crash-reports.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_position: 7 -title: Crash Reports ---- - -# Playground.WordPress.net Crash Reports - -When Playground crashes on Playground.WordPress.net users are able to submit a crash report. These reports are stored in the [#playground-logs channel on the Making WordPress Slack](https://wordpress.slack.com/archives/C06Q5DCKZ3L). - -**Playground doesn't collect crash reports automatically.** Instead, users are prompted to submit a crash report when a crash occurs and are able to modify it before submitting. The crash report includes a Playground logs, a description, and the url. - -## Development - -Logs are sent to the [logger API on Playground.WordPress.net](https://github.com/WordPress/wordpress-playground/blob/c52d7dbd94dbe3ffc57adde4d9844545ade97f93/packages/playground/website/public/logger.php). The logger API is a simple REST API that accepts a POST request with a `message` parameter. -The API validates the message and then sends it to the [#playground-logs channel on the Making WordPress Slack](https://wordpress.slack.com/archives/C06Q5DCKZ3L). - -### Slack app - -[We use the Playground Slack app](https://api.slack.com/apps/A06PEFZ00SG) to send logs to the #playground-logs channel. - -The [Slack app OAuth token](https://api.slack.com/apps/A06PEFZ00SG/oauth?) and channel id are stored on Playground.WordPress.net as environment variables in `.htaccess`. diff --git a/packages/docs/site/docs/_fragments/_limitations_ui.md b/packages/docs/site/docs/_fragments/_limitations_ui.md deleted file mode 100644 index 61883c3934..0000000000 --- a/packages/docs/site/docs/_fragments/_limitations_ui.md +++ /dev/null @@ -1,13 +0,0 @@ -### You can't access the Plugins or Themes Directory in the browser - -The web version of WordPress does not support network connections, so the plugin directory in wp-admin is not available. However, you can still upload plugins and open them with "?plugin=coblocks" or a similar query string. - -You can track the progress of adding network support in the browser at https://github.com/WordPress/wordpress-playground/issues/85. - -### When you refresh the page, you'll lose anything you did (unless you export it) - -In the web version of WordPress Playground, all database changes and uploads are gone once the page is refreshed. Preserving them would be useful for courses, technical demos, even sharing a link to your changes. - -Be sure to [export your work](../02-start-using/01-index.md#save-your-site) before you close the page. - -You can track the progress of support for persisting the changes at https://github.com/WordPress/wordpress-playground/issues/19 From 72e1f699a08bd7556db9f8a1e0230c8942c33e0c Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Wed, 1 May 2024 01:31:14 +0200 Subject: [PATCH 16/17] Add links to WP developer resource in relevant Blueprint steps --- .../playground/blueprints/src/lib/steps/define-site-url.ts | 6 +++--- .../blueprints/src/lib/steps/define-wp-config-consts.ts | 5 +++-- .../playground/blueprints/src/lib/steps/enable-multisite.ts | 2 +- .../blueprints/src/lib/steps/import-wordpress-files.ts | 4 ++-- packages/playground/blueprints/src/lib/steps/login.ts | 4 ++-- packages/playground/blueprints/src/lib/steps/request.ts | 2 +- .../blueprints/src/lib/steps/run-php-with-options.ts | 2 +- packages/playground/blueprints/src/lib/steps/run-php.ts | 1 + packages/playground/blueprints/src/lib/steps/site-data.ts | 6 +++--- packages/playground/blueprints/src/lib/steps/wp-cli.ts | 2 +- 10 files changed, 18 insertions(+), 16 deletions(-) diff --git a/packages/playground/blueprints/src/lib/steps/define-site-url.ts b/packages/playground/blueprints/src/lib/steps/define-site-url.ts index 5db0e405b4..45d80d7172 100644 --- a/packages/playground/blueprints/src/lib/steps/define-site-url.ts +++ b/packages/playground/blueprints/src/lib/steps/define-site-url.ts @@ -13,10 +13,10 @@ export interface DefineSiteUrlStep { } /** - * Sets WP_HOME and WP_SITEURL constants for the WordPress installation. + * Sets [`WP_HOME`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/#blog-address-url) and [`WP_SITEURL`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/#wp-siteurl) constants for the WordPress installation. * - * Beware: Using this step makes no sense on playground.wordpress.net. - * It is useful when you're building a custom Playground-based tool like wp-now, + * Using this step on playground.wordpress.net is moot. + * It is useful when building a custom Playground-based tool, like [`wp-now`](https://www.npmjs.com/package/@wp-now/wp-now), * or deploying Playground on a custom domain. * * @param playground The playground client. diff --git a/packages/playground/blueprints/src/lib/steps/define-wp-config-consts.ts b/packages/playground/blueprints/src/lib/steps/define-wp-config-consts.ts index 4a9151efef..469bd67b2d 100644 --- a/packages/playground/blueprints/src/lib/steps/define-wp-config-consts.ts +++ b/packages/playground/blueprints/src/lib/steps/define-wp-config-consts.ts @@ -23,13 +23,14 @@ export interface DefineWpConfigConstsStep { /** The constants to define */ consts: Record; /** - * The method of defining the constants. Possible values are: + * The method of defining the constants in wp-config.php. Possible values are: * * - rewrite-wp-config: Default. Rewrites the wp-config.php file to * explicitly call define() with the requested * name and value. This method alters the file * on the disk, but it doesn't conflict with * existing define() calls in wp-config.php. + * * - define-before-run: Defines the constant before running the requested * script. It doesn't alter any files on the disk, but * constants defined this way may conflict with existing @@ -45,7 +46,7 @@ export interface DefineWpConfigConstsStep { } /** - * Defines constants in a wp-config.php file. + * Defines constants in a [`wp-config.php`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/) file. * * This step can be called multiple times, and the constants will be merged. * diff --git a/packages/playground/blueprints/src/lib/steps/enable-multisite.ts b/packages/playground/blueprints/src/lib/steps/enable-multisite.ts index 0cffd6398e..6294e52a39 100644 --- a/packages/playground/blueprints/src/lib/steps/enable-multisite.ts +++ b/packages/playground/blueprints/src/lib/steps/enable-multisite.ts @@ -23,7 +23,7 @@ export interface EnableMultisiteStep { } /** - * Defines constants in a wp-config.php file. + * Defines the [Multisite](https://developer.wordpress.org/advanced-administration/multisite/create-network/) constants in a `wp-config.php` file. * * This step can be called multiple times, and the constants will be merged. * diff --git a/packages/playground/blueprints/src/lib/steps/import-wordpress-files.ts b/packages/playground/blueprints/src/lib/steps/import-wordpress-files.ts index 5b85c7725d..b4bac154c2 100644 --- a/packages/playground/blueprints/src/lib/steps/import-wordpress-files.ts +++ b/packages/playground/blueprints/src/lib/steps/import-wordpress-files.ts @@ -34,9 +34,9 @@ export interface ImportWordPressFilesStep { /** * Imports top-level WordPress files from a given zip file into - * the documentRoot. For example, if a zip file contains the + * the `documentRoot`. For example, if a zip file contains the * `wp-content` and `wp-includes` directories, they will replace - * the corresponding directories in Playground's documentRoot. + * the corresponding directories in Playground's `documentRoot`. * * Any files that Playground recognizes as "excluded from the export" * will carry over from the existing document root into the imported diff --git a/packages/playground/blueprints/src/lib/steps/login.ts b/packages/playground/blueprints/src/lib/steps/login.ts index 77ac4eb6ee..f00c4e3424 100644 --- a/packages/playground/blueprints/src/lib/steps/login.ts +++ b/packages/playground/blueprints/src/lib/steps/login.ts @@ -26,8 +26,8 @@ export type LoginStep = { }; /** - * Logs in to the Playground. - * Under the hood, this function submits the wp-login.php form + * Logs in to Playground. + * Under the hood, this function submits the [`wp-login.php`](https://developer.wordpress.org/reference/files/wp-login.php/) [form](https://developer.wordpress.org/reference/functions/wp_login_form/) * just like a user would. */ export const login: StepHandler = async ( diff --git a/packages/playground/blueprints/src/lib/steps/request.ts b/packages/playground/blueprints/src/lib/steps/request.ts index 5ecbbef283..7833338a5b 100644 --- a/packages/playground/blueprints/src/lib/steps/request.ts +++ b/packages/playground/blueprints/src/lib/steps/request.ts @@ -30,7 +30,7 @@ export interface RequestStep { } /** - * Sends a HTTP request to the Playground. + * Sends a HTTP request to Playground. */ export const request: StepHandler> = async ( playground, diff --git a/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts b/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts index 72181d178f..ae382b2c9d 100644 --- a/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts +++ b/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts @@ -21,7 +21,7 @@ import { PHPRunOptions } from '@php-wasm/universal'; export interface RunPHPWithOptionsStep { step: 'runPHPWithOptions'; /** - * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions) + * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions/)) */ options: PHPRunOptions; } diff --git a/packages/playground/blueprints/src/lib/steps/run-php.ts b/packages/playground/blueprints/src/lib/steps/run-php.ts index fa90cd31d2..c671cf4840 100644 --- a/packages/playground/blueprints/src/lib/steps/run-php.ts +++ b/packages/playground/blueprints/src/lib/steps/run-php.ts @@ -22,6 +22,7 @@ export interface RunPHPStep { /** * Runs PHP code. + * When running WordPress functions, the `code` key must first load [`wp-load.php`](https://github.com/WordPress/WordPress/blob/master/wp-load.php) and start with `"> = async ( playground, diff --git a/packages/playground/blueprints/src/lib/steps/site-data.ts b/packages/playground/blueprints/src/lib/steps/site-data.ts index 768c399467..6e4533bfca 100644 --- a/packages/playground/blueprints/src/lib/steps/site-data.ts +++ b/packages/playground/blueprints/src/lib/steps/site-data.ts @@ -25,8 +25,8 @@ export type SetSiteOptionsStep = { }; /** - * Sets site options. This is equivalent to calling `update_option` for each - * option in the `options` object. + * Sets site options. This is equivalent to calling [`update_option`](https://developer.wordpress.org/reference/functions/update_option/) for each + * option in the [`options`](https://developer.wordpress.org/apis/options/#available-options-by-category) object. */ export const setSiteOptions: StepHandler = async ( php, @@ -71,7 +71,7 @@ export interface UpdateUserMetaStep { } /** - * Updates user meta. This is equivalent to calling `update_user_meta` for each + * Updates user meta. This is equivalent to calling [`update_user_meta`](https://developer.wordpress.org/reference/functions/update_user_meta/) for each * meta value in the `meta` object. */ export const updateUserMeta: StepHandler = async ( diff --git a/packages/playground/blueprints/src/lib/steps/wp-cli.ts b/packages/playground/blueprints/src/lib/steps/wp-cli.ts index bb7622d915..c6c7397cc5 100644 --- a/packages/playground/blueprints/src/lib/steps/wp-cli.ts +++ b/packages/playground/blueprints/src/lib/steps/wp-cli.ts @@ -24,7 +24,7 @@ export interface WPCLIStep { } /** - * Runs PHP code. + * Runs PHP code using [WP-CLI](https://developer.wordpress.org/cli/commands/). */ export const wpCLI: StepHandler> = async ( playground, From c6fdc25b2819b88267a8a1e596f5f6a5deef4267 Mon Sep 17 00:00:00 2001 From: Ronny Shani <63248335+ironnysh@users.noreply.github.com> Date: Wed, 1 May 2024 18:22:29 +0000 Subject: [PATCH 17/17] Clarify Blueprint guidelines (Coding principles). --- .../docs/site/docs/13-contributing/03-coding-standards.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/packages/docs/site/docs/13-contributing/03-coding-standards.md b/packages/docs/site/docs/13-contributing/03-coding-standards.md index 66f72df238..a680fe3aad 100644 --- a/packages/docs/site/docs/13-contributing/03-coding-standards.md +++ b/packages/docs/site/docs/13-contributing/03-coding-standards.md @@ -35,18 +35,15 @@ Blueprint steps should be **concise and focused**. They should do one thing and - If you need to create a new step, try refactoring an existing one first. - If that's not enough, ensure the new step delivers a new capability. Don't replicate the functionality of existing steps. - -Blueprint steps should be **idempotent**, so you can run them multiple times and get similar results. - -- Assume the step would run more than once. +- Assume the step would be called more than once. - Assume it would run in a specific order. - Add unit tests to verify that. -- Define constants in virtual JSON files—don't modify PHP files. Blueprints should be **intuitive and straightforward**. - Don't require arguments that can be optional. - Use plain argument. For example, `slug` instead of `path`. +- Define constants in virtual JSON files—don't modify PHP files. - Define a TypeScript type for the Blueprint. That's how Playground generates its JSON schema. - Write a function to handle a Blueprint step. Accept the argument of the type you defined. - Provide a usage example in the doc string. It's automatically reflected in the docs.