Improve local development documentation

Author: chriszarate

CONTRIBUTING.md

@@ -4,12 +4,16 @@
 
 - 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 WordPress [PHP coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/), [JavaScript coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/) and [accessibility coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/). Accessibility in particular should be top of mind and thoroughly tested.
+- Contributors should review the WordPress [PHP coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/), [JavaScript coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/), and [accessibility coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/). Accessibility in particular should be top of mind and thoroughly tested.
 
-- You maintain copyright over any contribution you make. By submitting a pull request you agree to release that code under [Remote Data Blocks' license](LICENSE).
+- You maintain copyright over any contribution you make. By submitting a pull request, you agree to release that code under [our license](LICENSE).
 
 - When contributing to this repository, please first discuss the change you wish to make via an issue or discussion.
 
 ## Reporting security issues
 
 Please see [SECURITY.md](SECURITY.md).
+
+## Development environment
+
+Please see our guide to setting up a [local development environment](docs/local-development.md).

README.md

@@ -20,7 +20,7 @@ A [persistent object cache](https://developer.wordpress.org/reference/classes/wp
 ## Next steps
 
 > [!WARNING]
-> This plugin is still under heavy active development and breaking changes may land without warning. If you are interested in evaluating or testing this plugin, please [open an issue](https://github.com/Automattic/remote-data-blocks/issues/new/choose) and we'll be in touch!
+> This plugin is under heavy active development and breaking changes may land without warning. If you are interested in evaluating or testing this plugin, please [open an issue](https://github.com/Automattic/remote-data-blocks/issues/new/choose) and we'll be in touch!
 
 - Learn about the [core concepts](docs/concepts/index.md) behind Remote Data Blocks.
 - Follow along with [example workflows](docs/workflows/index.md) to see Remote Data Blocks in action.

docs/local-development.md

@@ -1,6 +1,6 @@
 # Local Development
 
-This repository includes tools for starting a development environment based on [`@wordpress/env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/), which requires Docker.
+This repository includes tools for starting a local development environment using [`@wordpress/env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/), which requires Docker and Docker Compose.
 
 ## Set up
 
@@ -14,13 +14,44 @@ composer install
 To start a development environment with Xdebug enabled:
 
 ```sh
-npm run start:monolith:xdebug
+npm run start:monolith-xdebug
 ```
 
 This will spin up a WordPress environment and a Valkey (Redis) instance for object cache. It will also build the block editor scripts, watch for changes, and open a Node.js debugging port. The WordPress environment will be available at `http://localhost:8888` (admin user: `admin`, password: `password`).
 
-To start a decoupled / headless development environment, make sure the [wp-components repo](https://github.com/Automattic/wp-components) is at a peer level in your file system and then run from root:
+Stop the development environment with `Ctrl+C` and resume it by running the same command. You can also manually stop the environment with `npm run stop`. Stopping the environment stops the WordPress containers but preserves their state.
+
+### Logs
+
+Watch logs from the WordPress container:
+
+```sh
+npx wp-env logs
+```
+
+### WP-CLI
+
+Run WP-CLI commands:
+
+```sh
+npm run wp-cli option get siteurl
+```
+
+### Destroy
+
+Destroy your local environment and irreversibly delete all content, configuration, and data:
 
 ```sh
-npm run start:decoupled
+npm run destroy
 ```
+
+## Local playground
+
+While not a suitable for local developement, it can sometimes be useful to quickly spin up a local WordPress playground using `@wp-now/wp-now`:
+
+```sh
+npm run build # or `npm run start` in a separate terminal
+npm run start:playground
+```
+
+Playgrounds do not closely mirror production environments and are missing persistent object cache, debugging tools, and other important features. Use `npm run start:monolith-xdebug` for local development.