Add documentation for package version constraints

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

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>

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

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 <package-name>:<version-constraint>
+```
+
+## 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).