Improve local development docs and start script

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.

bin/start

@@ -2,14 +2,34 @@
 
 set -e
 root_dir=$(pwd)
-script_dir=$(dirname "$0")
+env_type=$1
 
-# Cleanup after trapping SIGINT (Ctrl+C) and SIGTERM signals
+# Cleanup after error or trapping SIGINT (Ctrl+C) and SIGTERM signals
 cleanup() {
-    echo "Caught SIGINT signal. Shutting down..."
-    kill $BACKEND_PID 2>/dev/null || true
+    exit_code=0
+    echo ""
+
+    if [ -n "$1" ]; then
+        exit_code=1
+        echo "⚠️ Error: $1"
+    else
+        echo "✊ Caught SIG signal. Shutting down..."
+    fi
+
+    if [ -n "$BACKEND_PID" ]; then
+        echo "Killing npm start process..."
+        kill "$BACKEND_PID" 2>/dev/null || true
+    fi
+
+    echo "Shutting down Valkey / Redis..."
     docker compose -f "$root_dir/docker-compose.overrides.yml" down
-    exit 0
+
+    # This command echoes good status messages.
+    npx wp-env stop
+
+    echo ""
+    echo "⏸️ Run \`npm run start:$env_type\` to resume or \`npm run destroy\` to clean up."
+    exit "$exit_code"
 }
 
 setup_object_cache() {
@@ -20,40 +40,40 @@ setup_object_cache() {
 
 composer install
 
+trap 'cleanup' INT TERM
+
 # Monolith via wp-env
-if [ "$1" = "monolith" ]; then
+if [ "$env_type" = "monolith" ]; then
     # npx looks in node_modules/.bin first
-    npx wp-env start
     setup_object_cache
+    npx wp-env start
     npm start
     exit 0
 fi
 
 # Monolith w/xdebug via wp-env
-if [ "$1" = "monolith-xdebug" ]; then
-    npx wp-env start --xdebug
+if [ "$env_type" = "monolith-xdebug" ]; then
     setup_object_cache
+    npx wp-env start --xdebug=debug,develop,trace
     npm start
     exit 0
 fi
 
 # Decoupled via wp-env
-if [ "$1" = "decoupled" ]; then
+if [ "$env_type" = "decoupled" ]; then
     if [ ! -d "$root_dir/../wp-components" ]; then
-        echo "The wp-components repo does not exist. Please clone at sibling level to this repo."
+        echo "⚠️ The wp-components repo does not exist. Please clone at sibling level to this repo."
         exit 1
     fi
 
-    trap 'cleanup' SIGINT SIGTERM
     cd ./bin/wp-env/decoupled
 
-    npx wp-env start
     setup_object_cache
+    npx wp-env start
     npx wp-env run cli -- wp rewrite structure '/%postname%/'
 
     if [ $? -ne 0 ]; then
-        cleanup
-        exit 1
+        cleanup "Failed to set permalink structure"
     fi
 
     npm start &
@@ -62,5 +82,5 @@ if [ "$1" = "decoupled" ]; then
     exit 0
 fi
 
-echo "Error: can't start the unknown!"
+echo "⚠️ Error: can't start the unknown!"
 exit 1

bin/stop

@@ -1,15 +1,18 @@
 #!/bin/sh
 
 root_dir=$(pwd)
-script_dir=$(dirname "$0")
 
-echo "Shutting down..."
+echo "Shutting down Valkey / Redis..."
+docker compose -f "$root_dir/docker-compose.overrides.yml" down
 
-cd ./bin/wp-env/decoupled
+# We don't know which environment is running, so we'll stop both and suppress output.
+echo "Stopping WordPress..."
+cd ./bin/wp-env/decoupled || exit 1
 npx wp-env stop 2>/dev/null
-cd "$root_dir"
+cd "$root_dir" || exit 1
 npx wp-env stop 2>/dev/null
+
+# Kill any lingering Node.js processes.
 pkill -f 'remote-data-blocks/node_modules/'
-docker compose -f "$root_dir/docker-compose.overrides.yml" down
 
-echo "Shutdown complete"
+echo "⏸️ Rerun \`npm run start:*\` command to resume or \`npm run destroy\` to clean up."

blueprint.local.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
+  "meta": {
+    "title": "Remote Data Blocks local playground",
+    "description": "Runs Remote Data Blocks plugin in a local WordPress Playground",
+    "author": "WordPress VIP",
+    "categories": [ "Content" ]
+  },
+  "features": {
+    "networking": true
+  },
+  "landingPage": "/wp-admin/admin.php?page=remote-data-blocks-settings",
+  "login": true,
+  "phpExtensionBundles": [ "light" ],
+  "preferredVersions": {
+    "php": "8.2",
+    "wp": "latest"
+  },
+  "steps": [
+    {
+      "step": "setSiteOptions",
+      "options": {
+        "blogname": "Remote Data Blocks",
+        "blogdescription": "Explore the Remote Data Blocks plugin in a WordPress Playground"
+      }
+    },
+    {
+      "step": "installPlugin",
+      "options": {
+        "activate": true
+      },
+      "pluginZipFile": {
+        "resource": "wordpress.org/plugins",
+        "slug": "query-monitor"
+      }
+    },
+    {
+      "step": "activatePlugin",
+      "pluginPath": "remote-data-blocks/remote-data-blocks.php"
+    }
+  ]
+}

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.

package.json

@@ -39,7 +39,7 @@
     "start:decoupled": "./bin/start decoupled",
     "start:monolith": "./bin/start monolith",
     "start:monolith-xdebug": "./bin/start monolith-xdebug",
-    "start:playground": "npx @wp-now/wp-now start --php=8.2",
+    "start:playground": "npx @wp-now/wp-now start --php=8.2 --blueprint=blueprint.local.json",
     "start:playground:reset": "npm run start:playground -- --reset",
     "stop": "./bin/stop",
     "test": "npm run test:php && npm run test:js",

src/data-sources/constants.ts

@@ -15,7 +15,7 @@ export const SUPPORTED_SERVICES_LABELS: Record< ( typeof SUPPORTED_SERVICES )[ n
 		shopify: __( 'Shopify', 'remote-data-blocks' ),
 		'google-sheets': __( 'Google Sheets', 'remote-data-blocks' ),
 		'generic-http': __( 'HTTP', 'remote-data-blocks' ),
-		'example-api': __( 'Example API', 'remote-data-blocks' ),
+		'example-api': __( 'Conference Events Example API', 'remote-data-blocks' ),
 	} as const;
 export const OPTIONS_PAGE_SLUG = 'remote-data-blocks-settings';
 export const REST_BASE = '/remote-data-blocks/v1';