From b44a96af90b6770f8f73c99194bef680f2d2bc71 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 11:17:05 +0000 Subject: [PATCH 1/2] Initial plan From f9da8c6e60bc86757f10ea9bf59c46cd57fdf394 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 11:32:13 +0000 Subject: [PATCH 2/2] Add package version constraints documentation Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com> --- commands/package.md | 18 ++++ commands/package/install.md | 2 + guides.md | 1 + guides/package-version-constraints.md | 139 ++++++++++++++++++++++++++ 4 files changed, 160 insertions(+) create mode 100644 guides/package-version-constraints.md diff --git a/commands/package.md b/commands/package.md index 45bd52f5..38fe18c9 100644 --- a/commands/package.md +++ b/commands/package.md @@ -37,6 +37,24 @@ Learn how to create your own command from the --- Success: Package installed. + # Install a specific version of a package. + $ wp package install wp-cli/server-command:^2.0 + Installing package wp-cli/server-command (^2.0) + Updating /home/person/.wp-cli/packages/composer.json to require the package... + Using Composer to install the package... + --- + Loading composer repositories with package information + Updating dependencies + Resolving dependencies through SAT + Dependency resolution completed in 0.005 seconds + Analyzed 732 packages to resolve dependencies + Analyzed 1034 rules to resolve dependencies + - Installing package + Writing lock file + Generating autoload files + --- + Success: Package installed. + # Uninstall package. $ wp package uninstall wp-cli/server-command Removing require statement for package 'wp-cli/server-command' from /home/person/.wp-cli/packages/composer.json diff --git a/commands/package/install.md b/commands/package/install.md index 37cb2d48..7691dcaf 100644 --- a/commands/package/install.md +++ b/commands/package/install.md @@ -20,6 +20,8 @@ When installing a .zip file, WP-CLI extracts the package to `~/.wp-cli/packages/ 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 <GITHUB_TOKEN> Once this has been added, the value used for <GITHUB_TOKEN> will be used for future authorization requests. +For more information about version constraints, see the [Package Version Constraints](https://make.wordpress.org/cli/handbook/guides/package-version-constraints/) guide. + ### OPTIONS <name|git|path|zip> diff --git a/guides.md b/guides.md index af4d23b2..5377ad15 100644 --- a/guides.md +++ b/guides.md @@ -8,5 +8,6 @@ * **[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 * **[Identify a Plugin or Theme Conflict](https://make.wordpress.org/cli/handbook/guides/identify-plugin-theme-conflict/)** - Debugging advise +* **[Package Version Constraints](https://make.wordpress.org/cli/handbook/guides/package-version-constraints/)** - Learn about version constraint syntax for packages * **[Sharing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/sharing-wp-cli-packages/)** - Some words about your environment * **[Troubleshooting Guide](https://make.wordpress.org/cli/handbook/guides/troubleshooting/)** - Some help to troubleshoot diff --git a/guides/package-version-constraints.md b/guides/package-version-constraints.md new file mode 100644 index 00000000..71e85f51 --- /dev/null +++ b/guides/package-version-constraints.md @@ -0,0 +1,139 @@ +# Package Version Constraints + +When installing WP-CLI packages using the `wp package install` command, you can specify version constraints to control which version of a package is installed. This is particularly useful for ensuring compatibility, testing specific versions, or maintaining stability in production environments. + +## Syntax + +Version constraints are specified by appending a colon (`:`) followed by the constraint to the package name: + +```bash +wp package install : +``` + +## Common Version Constraints + +WP-CLI uses Composer's version constraint syntax. Here are the most commonly used constraints: + +### Exact Version + +Install a specific version: + +```bash +wp package install wp-cli/server-command:2.0.0 +``` + +### Version Range + +Install a version within a specific range: + +```bash +# Install any version >= 1.0 and < 2.0 +wp package install wp-cli/server-command:^1.0 + +# Install any version >= 1.2 and < 1.3 +wp package install wp-cli/server-command:~1.2 +``` + +### Stability Flags + +Install packages with specific stability requirements: + +```bash +# Install the latest stable release +wp package install wp-cli/server-command:@stable + +# Install the latest development version +wp package install wp-cli/server-command:@dev + +# Install the latest release candidate +wp package install wp-cli/server-command:@rc + +# Install the latest beta version +wp package install wp-cli/server-command:@beta + +# Install the latest alpha version +wp package install wp-cli/server-command:@alpha +``` + +### Wildcard Versions + +Use wildcards to match multiple versions: + +```bash +# Install any 1.x version +wp package install wp-cli/server-command:1.* + +# Install any 1.2.x version +wp package install wp-cli/server-command:1.2.* +``` + +### Development Branches + +Install directly from a development branch: + +```bash +# Install from the main branch +wp package install wp-cli/server-command:dev-main + +# Install from a feature branch +wp package install wp-cli/server-command:dev-feature-branch +``` + +## Caret (^) vs Tilde (~) Operators + +### Caret Operator (^) + +The caret operator allows updates that do not change the leftmost non-zero digit: + +- `^1.2.3` is equivalent to `>=1.2.3 <2.0.0` +- `^0.3.0` is equivalent to `>=0.3.0 <0.4.0` +- `^0.0.3` is equivalent to `>=0.0.3 <0.0.4` + +This is useful for semantic versioning, where you want to allow non-breaking changes. + +### Tilde Operator (~) + +The tilde operator allows the last digit specified to go up: + +- `~1.2.3` is equivalent to `>=1.2.3 <1.3.0` +- `~1.2` is equivalent to `>=1.2.0 <2.0.0` + +This is useful when you want to allow patch-level updates but not minor version updates. + +## Examples + +### Installing a Stable Package + +To install the latest stable version of a package: + +```bash +wp package install wp-cli/server-command:@stable +``` + +### Installing a Specific Version + +To install a specific version for testing or compatibility: + +```bash +wp package install wp-cli/server-command:1.0.0 +``` + +### Installing with Semantic Versioning + +To install a package and allow non-breaking updates: + +```bash +wp package install wp-cli/server-command:^2.0 +``` + +### Installing from a Development Branch + +To install the latest development version: + +```bash +wp package install wp-cli/server-command:dev-main +``` + +## Additional Resources + +For more detailed information about version constraints and advanced usage, see the official [Composer documentation on versions and constraints](https://getcomposer.org/doc/articles/versions.md).