From 7ef419674efc7653da17934835721afcf5d09658 Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Sat, 31 Jan 2026 13:09:45 -0800 Subject: [PATCH 1/4] Support directory arguments in JSON validation script Update the script to handle directory arguments by automatically appending '/**/*.json' to them, matching the behavior of 'lint-js'. Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- bin/validate-json.js | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/bin/validate-json.js b/bin/validate-json.js index 503845baba..834534cb03 100755 --- a/bin/validate-json.js +++ b/bin/validate-json.js @@ -236,7 +236,23 @@ async function validateFile( filePath ) { } const args = process.argv.slice( 2 ); -const patterns = args.length > 0 ? args : [ '**/*.json' ]; +const patterns = + args.length > 0 + ? args.map( ( arg ) => { + if ( + fs.existsSync( arg ) && + fs.statSync( arg ).isDirectory() + ) { + // Ensure that the glob patterns use forward slashes, as fast-glob requires them even on Windows + // and treats backslashes as escape characters. + return ( + arg.replace( /\\/g, '/' ).replace( /\/$/, '' ) + + '/**/*.json' + ); + } + return arg; + } ) + : [ '**/*.json' ]; ( async () => { const files = await fg( patterns, { From 9230940720643353d902c9aa0aaccc31e7ff3ffc Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Sat, 31 Jan 2026 14:23:55 -0800 Subject: [PATCH 2/4] Add lint and format meta scripts --- package.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/package.json b/package.json index ccd26a1f4e..094f4bf3b6 100644 --- a/package.json +++ b/package.json @@ -53,7 +53,9 @@ "build:plugin:web-worker-offloading": "webpack --mode production --env plugin=web-worker-offloading", "build:plugin:webp-uploads": "webpack --mode production --env plugin=webp-uploads", "generate-pending-release-diffs": "bin/generate-pending-release-diffs.sh", + "format": "npm run format-js && npm run format-php", "format-js": "wp-scripts format", + "lint": "npm run lint-js && npm run tsc && npm run lint-json && npm run lint-php && npm run phpstan", "lint-js": "wp-scripts lint-js", "lint-json": "node bin/validate-json.js", "tsc": "tsc", From 407834835f38b7e3559f906731c131cd52ef93b2 Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Sat, 31 Jan 2026 14:25:16 -0800 Subject: [PATCH 3/4] Improve AGENTS.md --- AGENTS.md | 84 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 49 insertions(+), 35 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 895382fe98..7fff4373ad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,10 +9,12 @@ This is a monorepo for the WordPress Performance Team, containing a collection o ### Project Structure +In this documentation, `` is a placeholder for one of the subdirectories under `/plugins`. + * `/bin`: Custom CLI commands and scripts for certain development workflows. * `/plugins`: The actual WordPress plugins that are developed in this monorepo. -* `/plugins/*`: An individual WordPress plugin folder. -* `/plugins/*/tests`: PHPUnit tests for the specific WordPress plugin. +* `/plugins/`: An individual WordPress plugin folder. +* `/plugins//tests`: PHPUnit tests for the specific WordPress plugin. * `/tools`: Setup and configuration files for various tools, such as linting and testing. ## Building and Running @@ -26,25 +28,58 @@ This is a monorepo for the WordPress Performance Team, containing a collection o ### Installation 1. Run `npm install` to install the Node.js dependencies. -2. Run `composer install` to install the PHP dependencies. -3. Run `npm run build` to do an initial build of the assets. +2. Run `npx husky` to ensure pre-commit hook (using `lint-staged`) is installed. +3. Run `composer install` to install the PHP dependencies. +4. Run `npm run build` to do an initial build of the JS and CSS assets. -### Building +### Production Builds -* To build the JavaScript and CSS assets: `npm run build` -* To build all plugins and place into the `build` directory: `npm run build-plugins` -* To build a specific plugin: `npm run build:plugin:` (e.g., `npm run build:plugin:performance-lab`) +* To build all plugins and place into the `build` directory: `npm run build-plugins`. +* To build a specific plugin: `npm run build:plugin:`. * To build ZIP files for distribution: `npm run build-plugins:zip` -### Running a Local Environment +### Running Local Environment This project uses `@wordpress/env` to create a local development environment. -* Check if the environment is already running: `npm run wp-env status` -* Start the environment: `npm run wp-env start` -* Stop the environment: `npm run wp-env stop` +* Start: `npx wp-env start` (with Xdebug: `npx wp-env start --xdebug`) +* Stop: `npx wp-env stop` +* Running a WP-CLI command: `npx wp-env run cli -- ` (e.g. `npx wp-env run cli -- wp post list`) + +Web environment URLs: + +* Development: `http://localhost:8888` (overridden by `port` in `.wp-env.override.json`) +* Test: `http://localhost:8889` (overridden by `testsPort` in `.wp-env.override.json`) + +### Testing + +* PHPUnit: + * Run tests for all plugins: `npm run test-php` (and in multisite: `npm run test-php-multisite`) + * Run tests for one plugin: `npm run test-php:` (and in multisite: `npm run test-php-multisite:`) +* End-to-end (E2E) tests: + * Run tests for all plugins: `npm run test-e2e` + * Run tests for one plugin: `npm run test-e2e:` (currently only `auto-sizes`) + +### Formatting + +* Format all files in the plugin: `npm run format` +* Format all PHP files: `composer format:all` +* Format all JavaScript, JSON, TypeScript, YAML files: `npm run format-js` + +When possible, scope formatting to just the file/plugin being modified: + +* Format JS files for a plugin: `npm run format-js plugins/` (or supply specific paths) +* Format all PHP files for a plugin: `composer format:` +* Format specific PHP files for a plugin: `composer format -- plugins//phpcs.xml.dist plugins//*.php` +* Format JavaScript, JSON, TypeScript, YAML files for a plugin: `npm run format-js plugins/` (or supply specific paths) + +### Static Analysis -The environment will by default be located at `http://localhost:8888` but this can be overridden by `.wp-env.override.json`. +Static analysis involves linting (ESLint, PHPCS), PHPStan (`composer phpstan`), and TypeScript (`npx tsc`). These are run automatically via a pre-commit hook, but they can be run manually. See the [lint-staged configuration](./lint-staged.config.js) for how to invoke. + +## Contributing a Change + +Ensure all changed code passes static analysis checks and unit tests. When possible, include unit tests with each change. A bug fix should include a test that reproduces the original issue before following up with a commit to fix the issue. ## Code Style @@ -68,7 +103,7 @@ Note that `lint-staged` will be used to automatically run code quality checks wi ### Indentation -In general, indentation should use tabs. Refer to `.editorconfig` in the project root for specifics. +In general, indentation should use tabs. Refer to [`.editorconfig`](./.editorconfig) in the project root for specifics. ### Inline Documentation @@ -161,24 +196,3 @@ export async function initialize( { log, onLCP, extendRootData } ) { // ... function definition for handleLCPMetric omitted ... ``` - -### Static Analysis Commands - -* **PHPStan**: `npm run phpstan` -* **TypeScript**: `npm run tsc` - -### Linting Commands - -* **JavaScript:** `npm run lint-js` -* **PHP:** `npm run lint-php` - -### Formatting Commands - -* **JavaScript:** `npm run format-js` -* **PHP:** `npm run format-php` - -### Testing Commands - -* **End-to-end (E2E) tests:** `npm run test-e2e` -* **PHP tests:** `npm run test-php` -* **PHP tests (multisite):** `npm run test-php-multisite` From f693e6a730ada8773e96370967653880988d217a Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Sun, 1 Feb 2026 16:19:23 -0800 Subject: [PATCH 4/4] Update AGENTS.md with AI guidelines and documentation links Added references to README.md, CONTRIBUTING.md, and WordPress AI Guidelines in the introduction. Included guidelines for disclosing AI tool usage in pull requests. --- AGENTS.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7fff4373ad..a1ca5e904a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Performance Lab -This is a monorepo for the WordPress Performance Team, containing a collection of standalone performance feature plugins. Refer to the [Performance Lab handbook](https://make.wordpress.org/performance/handbook/performance-lab/) for more details. +This is a monorepo for the WordPress Performance Team, containing a collection of standalone performance feature plugins. Refer to the [Performance Lab handbook](https://make.wordpress.org/performance/handbook/performance-lab/) for more details, as well as [README.md](../README.md) and [CONTRIBUTING.md](../CONTRIBUTING.md). See also the [WordPress AI Guidelines](https://make.wordpress.org/ai/handbook/ai-guidelines/). ## Project Overview @@ -81,6 +81,16 @@ Static analysis involves linting (ESLint, PHPCS), PHPStan (`composer phpstan`), Ensure all changed code passes static analysis checks and unit tests. When possible, include unit tests with each change. A bug fix should include a test that reproduces the original issue before following up with a commit to fix the issue. +Disclose AI tool usage in pull requests. Add a `Co-authored-by` Git commit message trailier indicating the agent when possible, for example one of: + +``` +Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> +Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> +Co-authored-by: Claude Opus 4.5 +``` + +All contributions released under GPLv2+ license, so generated code must be compatible. + ## Code Style In general, the [coding standards for WordPress](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/) should be followed: