Merge branch 'main' into main

swissspidy · web-flow · commit a64e441177ee · 2026-01-20T16:13:19.000+01:00
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ Long-form documentation (e.g. "Commands cookbook") can be edited directly.
 
 Internal API docs and command pages are generated dynamically from the WP-CLI codebase using the `wp handbook` series of commands.
 
-Before running these commands the bash script `bin/install-packages.sh` should be run to install the latest versions of the non-bundled commands in `bin/packages`. Note `wp` must point to the target WP-CLI instance, i.e. the phar/git that contains the docblocks to be generated against, and should be run with `WP_CLI_PACKAGES_DIR=bin/packages` and `WP_CLI_CONFIG_PATH=/dev/null`.
+Before running these commands, the bash script `bin/install_packages.sh` should be run to install the latest versions of the non-bundled commands in `bin/packages`. Note that `wp` must point to the target WP-CLI instance (i.e., the phar or git version that contains the docblocks to be generated against) and should be run with `WP_CLI_PACKAGES_DIR=bin/packages` and `WP_CLI_CONFIG_PATH=/dev/null`.
 
 So for instance to generate all dynamically created documentation against the nightly phar run:
 
diff --git a/bin/Handbook_Command.php b/bin/Handbook_Command.php
@@ -645,6 +645,15 @@ private static function gen_cmd_pages( $cmd, $parent = [], $verbose = false ) {
 			}
 			$docs = implode( "\n", $bits );
 
+			// Decode HTML entities inside backticks.
+			$docs = preg_replace_callback(
+				'/`([^`]*)`/',
+				function ( $matches ) {
+					return '`' . html_entity_decode( $matches[1], ENT_QUOTES | ENT_HTML401 ) . '`';
+				},
+				$docs
+			);
+
 			// Hack to prevent double encoding in code blocks.
 			$docs = preg_replace( '/ &lt; /', ' < ', $docs );
 			$docs = preg_replace( '/ &gt; /', ' > ', $docs );
diff --git a/bin/handbook-manifest.json b/bin/handbook-manifest.json
@@ -11,6 +11,12 @@
         "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/references\/behat-steps.md",
         "parent": "references"
     },
+    "behat-tests": {
+        "title": "Writing Behat Tests for WP-CLI",
+        "slug": "behat-tests",
+        "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/behat-tests.md",
+        "parent": "guides"
+    },
     "bug-reports": {
         "title": "Bug Reports",
         "slug": "bug-reports",
@@ -341,6 +347,12 @@
         "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/how-to\/how-to-start-webserver.md",
         "parent": "how-to"
     },
+    "figure-out-why-wordpress-is-slow": {
+        "title": "Figure out why WordPress is slow",
+        "slug": "figure-out-why-wordpress-is-slow",
+        "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/how-to\/figure-out-why-wordpress-is-slow.md",
+        "parent": "how-to"
+    },
     "identify-plugin-theme-conflict": {
         "title": "Identify a Plugin or Theme Conflict",
         "slug": "identify-plugin-theme-conflict",
@@ -371,6 +383,12 @@
         "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/references\/internal-api.md",
         "parent": "references"
     },
+    "licensing": {
+        "title": "Licensing",
+        "slug": "licensing",
+        "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/contributions\/licensing.md",
+        "parent": "contributions"
+    },
     "philosophy": {
         "title": "Philosophy",
         "slug": "philosophy",
diff --git a/commands/config/list.md b/commands/config/list.md
@@ -61,8 +61,8 @@ options:
     +------------------+------------------------------------------------------------------+----------+
     | key              | value                                                            | type     |
     +------------------+------------------------------------------------------------------+----------+
-    | AUTH_SALT        | n:]Xditk+_7&gt;Qi=>BmtZHiH-6/Ecrvl(V5ceeGP:{&gt;?;BT^=[B3-0&gt;,~F5z$(+Q$ | constant |
-    | SECURE_AUTH_SALT | ?Z/p|XhDw3w}?c.z%|+BAr|(Iv*H%%U+Du&amp;kKR y?cJOYyRVRBeB[2zF-`(&gt;+LCC | constant |
+    | AUTH_SALT        | n:]Xditk+_7>Qi=>BmtZHiH-6/Ecrvl(V5ceeGP:{>?;BT^=[B3-0>,~F5z$(+Q$ | constant |
+    | SECURE_AUTH_SALT | ?Z/p|XhDw3w}?c.z%|+BAr|(Iv*H%%U+Du&kKR y?cJOYyRVRBeB[2zF-`(&gt;+LCC | constant |
     | LOGGED_IN_SALT   | +$@(1{b~Z~s}Cs&gt;8Y]6[m6~TnoCDpE&gt;O%e75u}&amp;6kUH!&gt;q:7uM4lxbB6[1pa_X,q | constant |
     | NONCE_SALT       | _x+F li|QL?0OSQns1_JZ{|Ix3Jleox-71km/gifnyz8kmo=w-;@AE8W,(fP&lt;N}2 | constant |
     +------------------+------------------------------------------------------------------+----------+
diff --git a/commands/core/verify-checksums.md b/commands/core/verify-checksums.md
@@ -8,7 +8,7 @@ Downloads md5 checksums for the current version from WordPress.org, and compares
 
 For security, avoids loading WordPress when verifying checksums.
 
-If you experience issues verifying from this command, ensure you are passing the relevant `--locale` and `--version` arguments according to the values from the `Dashboard-&gt;Updates` menu in the admin area of the site.
+If you experience issues verifying from this command, ensure you are passing the relevant `--locale` and `--version` arguments according to the values from the `Dashboard->Updates` menu in the admin area of the site.
 
 ### OPTIONS
 
diff --git a/commands/find.md b/commands/find.md
@@ -58,7 +58,7 @@ These fields will be displayed by default for each installation:
 
 These fields are optionally available:
 
-* wp_path - Path that can be passed to `--path=&lt;path&gt;` global parameter.
+* wp_path - Path that can be passed to `--path=<path>` global parameter.
 * db_host - Host name for the database.
 * db_user - User name for the database.
 * db_name - Database name for the database.
diff --git a/commands/package/install.md b/commands/package/install.md
@@ -15,7 +15,7 @@ Packages are installed to `~/.wp-cli/packages/` by default. Use the `WP_CLI_PACK
 
 When installing a local directory, WP-CLI simply registers a reference to the directory. If you move or delete the directory, WP-CLI's reference breaks.
 
-When installing a .zip file, WP-CLI extracts the package to `~/.wp-cli/packages/local/&lt;package-name&gt;`.
+When installing a .zip file, WP-CLI extracts the package to `~/.wp-cli/packages/local/<package-name>`.
 
 If Github token authorization is required, a GitHub Personal Access Token (https://github.com/settings/tokens) can be used. The following command will add a GitHub Personal Access Token to Composer's global configuration:
 composer config -g github-oauth.github.com &lt;GITHUB_TOKEN&gt; Once this has been added, the value used for &lt;GITHUB_TOKEN&gt; will be used for future authorization requests.
diff --git a/commands/profile/eval-file.md b/commands/profile/eval-file.md
@@ -42,7 +42,7 @@ options:
 
 ### EXAMPLES
 
-    # Profile from a file `request.php` containing `&lt;?php wp_remote_get( "https://www.apple.com/" );`.
+    # Profile from a file `request.php` containing `<?php wp_remote_get( "https://www.apple.com/" );`.
     $ wp profile eval-file request.php --fields=time,cache_ratio,request_count
     +---------+-------------+---------------+
     | time    | cache_ratio | request_count |
diff --git a/commands/scaffold/block.md b/commands/scaffold/block.md
@@ -34,7 +34,7 @@ options:
 \---
 
 [\--theme]
-: Create files in the active theme directory. Specify a theme with `--theme=&lt;theme&gt;` to have the file placed in that theme.
+: Create files in the active theme directory. Specify a theme with `--theme=<theme>` to have the file placed in that theme.
 
 [\--plugin=&lt;plugin&gt;]
 : Create files in the given plugin's directory.
diff --git a/commands/scaffold/cpt.md b/commands/scaffold/cpt.md
@@ -21,7 +21,7 @@ See the [argument syntax](https://make.wordpress.org/cli/handbook/references/arg
 : The dashicon to use in the menu.
 
 [\--theme]
-: Create a file in the active theme directory, instead of sending to STDOUT. Specify a theme with `--theme=&lt;theme&gt;` to have the file placed in that theme.
+: Create a file in the active theme directory, instead of sending to STDOUT. Specify a theme with `--theme=<theme>` to have the file placed in that theme.
 
 [\--plugin=&lt;plugin&gt;]
 : Create a file in the given plugin's directory, instead of sending to STDOUT.
diff --git a/commands/scaffold/plugin-tests.md b/commands/scaffold/plugin-tests.md
@@ -5,7 +5,7 @@ Generates files needed for running PHPUnit tests in a plugin.
 The following files are generated by default:
 
 * `phpunit.xml.dist` is the configuration file for PHPUnit.
-* `.circleci/config.yml` is the configuration file for CircleCI. Use `--ci=&lt;provider&gt;` to select a different service.
+* `.circleci/config.yml` is the configuration file for CircleCI. Use `--ci=<provider>` to select a different service.
 * `bin/install-wp-tests.sh` configures the WordPress test suite and a test database.
 * `tests/bootstrap.php` is the file that makes the current plugin active when running the test suite.
 * `tests/test-sample.php` is a sample file containing the actual tests.
diff --git a/commands/scaffold/plugin.md b/commands/scaffold/plugin.md
@@ -15,7 +15,7 @@ The following files are always generated:
 The following files are also included unless the `--skip-tests` is used:
 
 * `phpunit.xml.dist` is the configuration file for PHPUnit.
-* `.circleci/config.yml` is the configuration file for CircleCI. Use `--ci=&lt;provider&gt;` to select a different service.
+* `.circleci/config.yml` is the configuration file for CircleCI. Use `--ci=<provider>` to select a different service.
 * `bin/install-wp-tests.sh` configures the WordPress test suite and a test database.
 * `tests/bootstrap.php` is the file that makes the current plugin active when running the test suite.
 * `tests/test-sample.php` is a sample file containing test cases.
diff --git a/commands/scaffold/post-type.md b/commands/scaffold/post-type.md
@@ -21,7 +21,7 @@ See the [argument syntax](https://make.wordpress.org/cli/handbook/references/arg
 : The dashicon to use in the menu.
 
 [\--theme]
-: Create a file in the active theme directory, instead of sending to STDOUT. Specify a theme with `--theme=&lt;theme&gt;` to have the file placed in that theme.
+: Create a file in the active theme directory, instead of sending to STDOUT. Specify a theme with `--theme=<theme>` to have the file placed in that theme.
 
 [\--plugin=&lt;plugin&gt;]
 : Create a file in the given plugin's directory, instead of sending to STDOUT.
diff --git a/commands/scaffold/tax.md b/commands/scaffold/tax.md
@@ -21,7 +21,7 @@ See the [argument syntax](https://make.wordpress.org/cli/handbook/references/arg
 : The textdomain to use for the labels.
 
 [\--theme]
-: Create a file in the active theme directory, instead of sending to STDOUT. Specify a theme with `--theme=&lt;theme&gt;` to have the file placed in that theme.
+: Create a file in the active theme directory, instead of sending to STDOUT. Specify a theme with `--theme=<theme>` to have the file placed in that theme.
 
 [\--plugin=&lt;plugin&gt;]
 : Create a file in the given plugin's directory, instead of sending to STDOUT.
diff --git a/commands/scaffold/taxonomy.md b/commands/scaffold/taxonomy.md
@@ -21,7 +21,7 @@ See the [argument syntax](https://make.wordpress.org/cli/handbook/references/arg
 : The textdomain to use for the labels.
 
 [\--theme]
-: Create a file in the active theme directory, instead of sending to STDOUT. Specify a theme with `--theme=&lt;theme&gt;` to have the file placed in that theme.
+: Create a file in the active theme directory, instead of sending to STDOUT. Specify a theme with `--theme=<theme>` to have the file placed in that theme.
 
 [\--plugin=&lt;plugin&gt;]
 : Create a file in the given plugin's directory, instead of sending to STDOUT.
diff --git a/commands/scaffold/theme-tests.md b/commands/scaffold/theme-tests.md
@@ -5,7 +5,7 @@ Generates files needed for running PHPUnit tests in a theme.
 The following files are generated by default:
 
 * `phpunit.xml.dist` is the configuration file for PHPUnit.
-* `.circleci/config.yml` is the configuration file for CircleCI. Use `--ci=&lt;provider&gt;` to select a different service.
+* `.circleci/config.yml` is the configuration file for CircleCI. Use `--ci=<provider>` to select a different service.
 * `bin/install-wp-tests.sh` configures the WordPress test suite and a test database.
 * `tests/bootstrap.php` is the file that makes the current theme active when running the test suite.
 * `tests/test-sample.php` is a sample file containing the actual tests.
diff --git a/commands/site/empty.md b/commands/site/empty.md
@@ -12,8 +12,8 @@ To also empty custom database tables, you'll need to hook into command execution
 WP_CLI::add_hook( 'after_invoke:site empty', function(){
     global $wpdb;
     foreach( array( 'p2p', 'p2pmeta' ) as $table ) {
-        $table = $wpdb-&gt;$table;
-        $wpdb-&gt;query( "TRUNCATE $table" );
+        $table = $wpdb->$table;
+        $wpdb->query( "TRUNCATE $table" );
     }
 });
 ```
diff --git a/commands/transient/set.md b/commands/transient/set.md
@@ -2,7 +2,7 @@
 
 Sets a transient value.
 
-`&lt;expiration&gt;` is the time until expiration, in seconds.
+`<expiration>` is the time until expiration, in seconds.
 
 For a more complete explanation of the transient cache, including the network|site cache, please see docs for `wp transient`.
 
diff --git a/contributions.md b/contributions.md
@@ -5,6 +5,7 @@
 * **[WordCamp Contributor Day](https://make.wordpress.org/cli/handbook/contributions/contributor-day/)** - Quick-start guide for WordCamp Contributor Days.
 * **[Ideas](https://github.com/wp-cli/ideas)** - Up-vote existing ideas or submit your own.
 * **[Governance](https://make.wordpress.org/cli/handbook/contributions/governance/)** - Summary of those behind WP-CLI.
+* **[Licensing](https://make.wordpress.org/cli/handbook/contributions/licensing/)** - License requirements for third-party code and dependencies.
 * **[Implementation details](https://make.wordpress.org/cli/handbook/contributions/implementation-details/)** - Catalog of historical design decisions.
 * **[Philosophy](https://make.wordpress.org/cli/handbook/contributions/philosophy/)** - Guidelines which inform project scope, command organization, and behavior.
 * **[Pull requests](https://make.wordpress.org/cli/handbook/contributions/pull-requests/)** - Submit your first bug fix or new feature.
diff --git a/contributions/licensing.md b/contributions/licensing.md
@@ -0,0 +1,46 @@
+# Licensing
+
+WP-CLI is licensed under the [MIT license](https://github.com/wp-cli/wp-cli/blob/master/LICENSE). This document outlines WP-CLI's licensing expectations for third-party code.
+
+## Accepting third-party code into the official repository/organization
+
+All code accepted into repositories under the official [WP-CLI GitHub organization](https://github.com/wp-cli) must be compatible with the MIT license. This ensures that WP-CLI can remain freely usable, modifiable, and distributable by anyone.
+
+## Bundling third-party code
+
+When bundling third-party code directly into a WP-CLI package (i.e., copying code into the repository rather than declaring it as a dependency), the code must:
+
+1. **Be licensed under an MIT-compatible license**
+2. **Include the original license file or header** - The third-party code's license terms must be preserved
+3. **Maintain copyright notices** - Original copyright notices must remain intact
+4. **Be clearly identified** - It should be clear which code is third-party and where it came from
+
+When in doubt about whether to bundle third-party code, consider using it as a dependency through Composer instead.
+
+## Depending on third-party code
+
+Third-party packages declared as dependencies (through Composer or other package managers) must be licensed under MIT-compatible licenses. This applies to both:
+
+* **Direct dependencies** - Packages explicitly listed in `composer.json`
+* **Transitive dependencies** - Dependencies of your dependencies
+
+### Checking dependency licenses
+
+Before adding a new dependency:
+
+1. Check the dependency's `LICENSE` file or `composer.json` for license information
+2. Verify that all of the dependency's own dependencies are also compatible
+3. Use `composer show -t` to view the dependency tree with license information, or install additional tools like `composer/satis` to run `composer licenses` for detailed license auditing
+
+## Why these requirements?
+
+These licensing requirements ensure that:
+
+1. **WP-CLI remains free and open** - Users can use, modify, and distribute WP-CLI without legal concerns
+2. **Commercial use is permitted** - Companies can use and integrate WP-CLI into their products
+3. **No license conflicts** - All code in the WP-CLI ecosystem is legally compatible
+4. **Simplicity for users** - Users don't need to track multiple license requirements
+
+## Questions?
+
+If you have questions about licensing or need clarification on whether a specific license is compatible, please open an issue or contact the [WP-CLI maintainers](https://github.com/orgs/wp-cli/teams/maintainers).
diff --git a/contributions/pull-requests.md b/contributions/pull-requests.md
@@ -118,9 +118,11 @@ To fix the errors and warnings that can be automatically fixed:
 
 ### Functional tests
 
-WP-CLI uses [Behat](https://behat.org/) as its functional test suite. Stability between releases is an important contact WP-CLI makes with its users. Functional tests are different than unit tests in that they execute the entire WP-CLI command, and ensure they always work as expected.
+WP-CLI uses [Behat](https://behat.org/) for functional testing. Functional tests ensure commands work as expected by executing them end-to-end.
 
-Every repository has a `features/` directory with one or more [YAML](https://yaml.org/)-formatted `*.feature` files. Here's an example of what you might see:
+For a comprehensive guide on writing and running Behat tests, see **[Writing Behat Tests](https://make.wordpress.org/cli/handbook/guides/behat-tests/)**.
+
+Here's a quick example of what a Behat test looks like:
 
 ```yml
 Feature: Manage WordPress options
@@ -143,14 +145,6 @@ In this example:
 - `When` causes an event to occur.
 - `Then` asserts what's expected after the event is complete.
 
-In a slightly more human-friendly form:
-
-> I have a WordPress installation. When I run `wp option get home`, then the output from the command should be 'https://example.org'.
-
-Essentially, WP-CLI's functional test suite lets you _describe how a command should work_, and then run that description as a functional test.
-
-Notably, Behat is simply the framework for writing these tests. We've written our own custom `Given`, `When`, and `Then` step definitions ([example](https://github.com/wp-cli/wp-cli-tests/blob/560ed5ca2776b6b3b66c79a6e6dc62904ae20b3b/src/Context/GivenStepDefinitions.php#L105-L110), [example](https://github.com/wp-cli/wp-cli-tests/blob/560ed5ca2776b6b3b66c79a6e6dc62904ae20b3b/src/Context/WhenStepDefinitions.php#L34-L42)).
-
 #### Creating a test database
 
 Before running the functional tests, you'll need a MySQL (or MariaDB) user called `wp_cli_test` with the password `password1` that has full privileges on the MySQL database `wp_cli_test`.
diff --git a/guides.md b/guides.md
@@ -4,6 +4,7 @@
 * **[Quick start](https://make.wordpress.org/cli/handbook/guides/quick-start/)** - Where to begin after you've installed WP-CLI for the first time.
 * **[Running commands remotely](https://make.wordpress.org/cli/handbook/guides/running-commands-remotely/)** - Learn how to remotely control multiple servers at once. 
 * **[Commands cookbook](https://make.wordpress.org/cli/handbook/guides/commands-cookbook/)** - The full 101 how commands work, writing your own, and sharing them with the world.
+* **[Writing Behat Tests](https://make.wordpress.org/cli/handbook/guides/behat-tests/)** - How to write and run Behat tests for WP-CLI commands and packages.
 * **[Common issues and their fixes](https://make.wordpress.org/cli/handbook/guides/common-issues/)** - In case of fire, break glass.
 * **[External resources](https://make.wordpress.org/cli/handbook/guides/external-resources/)** - Blog posts, slides and videos from users.
 * **[Force output to a specific locale](https://make.wordpress.org/cli/handbook/guides/force-output-specific-locale/)** - Localisation issue
diff --git a/guides/behat-tests.md b/guides/behat-tests.md
diff --git a/guides/external-resources.md b/guides/external-resources.md
diff --git a/how-to.md b/how-to.md
diff --git a/how-to/figure-out-why-wordpress-is-slow.md b/how-to/figure-out-why-wordpress-is-slow.md
diff --git a/index.md b/index.md
