From c817f41951391f3a558ec40033d23a03e53f3f00 Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Mon, 19 Aug 2024 11:53:28 -0500
Subject: [PATCH] Document the effect of ordering on package priority (#6211)

Closes https://github.com/astral-sh/uv/issues/6209
Closes https://github.com/astral-sh/uv/issues/5474
---
 PIP_COMPATIBILITY.md      | 8 ++++++++
 crates/uv-cli/src/lib.rs  | 9 +++++++--
 docs/pip/compatibility.md | 8 ++++++++
 docs/reference/cli.md     | 6 +++++-
 4 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/PIP_COMPATIBILITY.md b/PIP_COMPATIBILITY.md
index 87e7db20d09b..fea23ff74fe1 100644
--- a/PIP_COMPATIBILITY.md
+++ b/PIP_COMPATIBILITY.md
@@ -447,3 +447,11 @@ is omitted.
 While this is not strictly compliant with [PEP 440](https://peps.python.org/pep-0440/), it _is_
 consistent with
 [pip](https://github.com/pypa/pip/blob/24.1.1/src/pip/_internal/resolution/resolvelib/candidates.py#L540).
+
+## Package priority
+
+There are usually many possible solutions given a set of requirements — a resolver must choose
+between the solutions. Unlike pip, uv's resolver uses the ordering provided of packages to determine
+the default priority. This means that uv's resolution can differ based on the order of the packages.
+For example, `uv pip install foo bar` would prioritize a newer version of `foo` over `bar`.
+Similarly, this applies to the ordering of requirements in input files to `uv pip compile`.
diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs
index cfa91fb79274..b4fd5cdf1ac2 100644
--- a/crates/uv-cli/src/lib.rs
+++ b/crates/uv-cli/src/lib.rs
@@ -692,10 +692,13 @@ fn parse_maybe_file_path(input: &str) -> Result<Maybe<PathBuf>, String> {
 pub struct PipCompileArgs {
     /// Include all packages listed in the given `requirements.in` files.
     ///
-    /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will
-    /// extract the requirements for the relevant project.
+    /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will extract the
+    /// requirements for the relevant project.
     ///
     /// If `-` is provided, then requirements will be read from stdin.
+    ///
+    /// The order of the requirements files and the requirements in them is used to determine
+    /// priority during resolution.
     #[arg(required(true), value_parser = parse_file_path)]
     pub src_file: Vec<PathBuf>,
 
@@ -1245,6 +1248,8 @@ pub struct PipSyncArgs {
 #[allow(clippy::struct_excessive_bools)]
 pub struct PipInstallArgs {
     /// Install all listed packages.
+    ///
+    /// The order of the packages is used to determine priority during resolution.
     #[arg(group = "sources")]
     pub package: Vec<String>,
 
diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md
index d5ed28486946..e3747c04fe39 100644
--- a/docs/pip/compatibility.md
+++ b/docs/pip/compatibility.md
@@ -395,3 +395,11 @@ will include all index URLs when `--emit-index-url` is passed, including the def
 By default, uv does not write any `--no-build` or `--only-binary` options to the output file, unlike
 `pip-compile`. To include these options in the output file, pass the `--emit-build-options` flag to
 `uv pip compile`.
+
+## Package priority
+
+There are usually many possible solutions given a set of requirements — a resolver must choose
+between the solutions. Unlike pip, uv's resolver uses the ordering provided of packages to determine
+the default priority. This means that uv's resolution can differ based on the order of the packages.
+For example, `uv pip install foo bar` would prioritize a newer version of `foo` over `bar`.
+Similarly, this applies to the ordering of requirements in input files to `uv pip compile`.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 36da9eac7696..92598e18a4b3 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -3546,6 +3546,8 @@ uv pip compile [OPTIONS] <SRC_FILE>...
 
 <p>If <code>-</code> is provided, then requirements will be read from stdin.</p>
 
+<p>The order of the requirements files and the requirements in them is used to determine priority during resolution.</p>
+
 </dd></dl>
 
 <h3 class="cli-reference">Options</h3>
@@ -4191,7 +4193,9 @@ uv pip install [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>|--editable <EDITAB
 
 <h3 class="cli-reference">Arguments</h3>
 
-<dl class="cli-reference"><dt><code>PACKAGE</code></dt><dd><p>Install all listed packages</p>
+<dl class="cli-reference"><dt><code>PACKAGE</code></dt><dd><p>Install all listed packages.</p>
+
+<p>The order of the packages is used to determine priority during resolution.</p>
 
 </dd></dl>