Merge pull request #587 from wp-cli/copilot/add-documentation-version-constraints

Author: swissspidy

guides.md

@@ -9,5 +9,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
+* **[Installing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/installing-packages/)** - Learn how to install packages and use version constraints
 * **[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/installing-packages.md

@@ -0,0 +1,61 @@
+# Installing WP-CLI Packages
+
+WP-CLI packages are community-maintained projects built on WP-CLI. They can contain WP-CLI commands, but they can also just extend WP-CLI in some way.
+
+To find existing packages to install, take a look at [Packagist](https://packagist.org/?type=wp-cli-package).
+
+## Installing a Package
+
+Use the `wp package install` command to install a package. Packages can be specified as:
+
+* Package name from WP-CLI's package index
+* Git URL accessible by the current shell user
+* Path to a directory on the local machine
+* Local or remote .zip file
+
+```bash
+# Install a package by name
+wp package install wp-cli/server-command
+
+# Install from a Git URL
+wp package install https://github.com/wp-cli/server-command.git
+
+# Install from a local directory
+wp package install /path/to/package
+
+# Install from a .zip file
+wp package install package.zip
+```
+
+Packages are installed to `~/.wp-cli/packages/` by default. Use the `WP_CLI_PACKAGES_DIR` environment variable to provide a custom path. See also: [Sharing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/sharing-wp-cli-packages/).
+
+## Version Constraints
+
+When installing WP-CLI packages, you can specify version constraints to control which version of a package is installed.
+
+Version constraints are specified by appending a colon (`:`) followed by the constraint to the package name:
+
+```bash
+wp package install <package-name>:<version-constraint>
+```
+
+WP-CLI uses Composer's version constraint syntax. Here are some commonly used examples:
+
+```bash
+# Install a specific version
+wp package install wp-cli/server-command:2.0.0
+
+# Install with caret operator (allows non-breaking updates)
+wp package install wp-cli/server-command:^1.0
+
+# Install with tilde operator (allows patch-level updates)
+wp package install wp-cli/server-command:~1.2
+
+# Install the latest stable release
+wp package install wp-cli/server-command:@stable
+
+# Install from a development branch
+wp package install wp-cli/server-command:dev-main
+```
+
+For complete documentation on version constraint syntax and operators, see the [Composer documentation on versions and constraints](https://getcomposer.org/doc/articles/versions.md).

references/tools.md

@@ -1,6 +1,6 @@
 # Tools
 
-The following is a list of projects that integrate with WP-CLI in some form. For installable WP-CLI packages, please see the [package index](https://wp-cli.org/package-index/).
+The following is a list of projects that integrate with WP-CLI in some form. For installable WP-CLI packages, take a look at [Packagist](https://packagist.org/?type=wp-cli-package).
 
 ## Plugins