From 396dbaf6576cf976fa5e1e9f7c80a16b6da5b563 Mon Sep 17 00:00:00 2001 From: Noah Allen Date: Thu, 4 Aug 2022 16:19:43 -0700 Subject: [PATCH] Update readme and documentation --- packages/env/CHANGELOG.md | 3 +++ packages/env/README.md | 28 ++++++++++++++++------------ 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/packages/env/CHANGELOG.md b/packages/env/CHANGELOG.md index 0c128c813684f..bb83b6335d860 100644 --- a/packages/env/CHANGELOG.md +++ b/packages/env/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +### Enhancement +- Previously, wp-env used the WordPress version provided by Docker in the WordPress image for installations which don't specify a WordPress version. Now, wp-env will find the latest stable version on WordPress.org and check out the https://github.com/WordPress/WordPress repository at the tag matching that version. In most cases, this will match what Docker provides. The benefit is that wp-env (and WordPress.org) now controls the default WordPress version rather than Docker. + ## 5.0.0 (2022-07-27) ### Breaking Changes diff --git a/packages/env/README.md b/packages/env/README.md index fad2d008a3ce9..af7aa69b3beb5 100644 --- a/packages/env/README.md +++ b/packages/env/README.md @@ -16,7 +16,7 @@ The local environment will be available at http://localhost:8888 (Username: `adm ## Prerequisites -`wp-env` requires Docker to be installed. There are instructions available for installing Docker on [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [all other versions of Windows](https://docs.docker.com/toolbox/toolbox_install_windows/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script). +`wp-env` requires Docker to be installed. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/). Node.js and NPM are required. The latest LTS version of Node.js is used to develop `wp-env` and is recommended. @@ -40,7 +40,9 @@ If your project already has a package.json, it's also possible to use `wp-env` a $ npm i @wordpress/env --save-dev ``` -Then modify your package.json and add an extra command to npm `scripts` (https://docs.npmjs.com/misc/scripts): +At this point, you can use the local, project-level version of wp-env via [`npx`](https://www.npmjs.com/package/npx), a utility automatically installed with `npm`.`npx` finds binaries like wp-env installed through node modules. As an example: `npx wp-env start --update`. + +If you don't wish to use `npx`, modify your package.json and add an extra command to npm `scripts` (https://docs.npmjs.com/misc/scripts): ```json "scripts": { @@ -51,7 +53,7 @@ Then modify your package.json and add an extra command to npm `scripts` (https:/ When installing `wp-env` in this way, all `wp-env` commands detailed in these docs must be prefixed with `npm run`, for example: ```sh -# You must add another double dash to pass the "update" flag to wp-env +# You must add another double dash to pass flags to the script (wp-env) rather than to npm itself $ npm run wp-env start -- --update ``` @@ -117,15 +119,14 @@ Running `docker ps` and inspecting the `PORTS` column allows you to determine wh You may also specify the port numbers in your `.wp-env.json` file, but the environment variables take precedent. -### 3. Restart `wp-env` +### 3. Restart `wp-env` with updates Restarting `wp-env` will restart the underlying Docker containers which can fix many issues. -To restart `wp-env`: +To restart `wp-env`, just run `wp-env start` again. It will automatically stop and start the container. If you also pass the `--update` argument, it will download updates and configure WordPress agian. ```sh -$ wp-env stop -$ wp-env start +$ wp-env start --update ``` ### 4. Restart Docker @@ -156,16 +157,17 @@ $ wp-env clean all $ wp-env start ``` -### 6. Nuke everything and start again 🔥 +### 6. Destroy everything and start again 🔥 -When all else fails, you can use `wp-env destroy` to forcibly remove all of the underlying Docker containers and volumes. This will allow you to start from scratch. +When all else fails, you can use `wp-env destroy` to forcibly remove all of the underlying Docker containers, volumes, and files. This will allow you to start from scratch. -To nuke everything: +To do so: **⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.** ```sh $ wp-env destroy +# This new instance is a fresh start with no existing data: $ wp-env start ``` @@ -211,10 +213,12 @@ wp-env start wp-env start --xdebug=profile,trace,debug ``` -When you're running `wp-env` using `npm run`, like when working in the Gutenberg repo or when having `wp-env` as a local project dependency, don't forget to add an extra double dash before the `--xdebug` command: +When you're running `wp-env` using `npm run`, like when working in the Gutenberg repo or when `wp-env` is a local project dependency, don't forget to add an extra double dash before the `--xdebug` command: ```sh npm run wp-env start -- --xdebug +# Alternatively, use npx: +npx wp-env start --xdebug ``` If you forget about that, the `--xdebug` parameter will be passed to NPM instead of the `wp-env start` command and it will be ignored. @@ -532,7 +536,7 @@ Additionally, the values referencing a URL include the specified port for the gi ### Examples -#### Latest production WordPress + current directory as a plugin +#### Latest stable WordPress + current directory as a plugin This is useful for plugin development.