Add uv add --bounds to configure the version constraint (#12946)

By default, uv uses only a lower bound in `uv add`, which avoids
dependency conflicts due to upper bounds. With this PR, this cna be
changed by setting a different bound kind. The bound kind can be
configured in `uv.toml`, as a user preference, in `pyproject.toml`, as a
project preference, or on the CLI, when adding a specific project.

We add two options that add an upper bound on the constraint, one for
SemVer (`>=1.2.3,<2.0.0`, dubbed "major", modeled after the SemVer
caret) and another one for dependencies that make breaking changes in
minor version (`>=1.2.3,<1.3.0`, dubbed "minor", modeled after the
SemVer tilde). Intuitively, the major option bumps the most significant
version component, while the minor option bumps the second most
significant version component. There is also an exact bounds option
(`==1.2.3`), though generally we recommend setting a wider bound and
using the lockfile for pinning.

Versions can have leading zeroes, such as `0.1` or `0.0.1`. For a single
leading 0, we shift the the meaning of major and minor similar to cargo.
For two or more leading zeroes, the difference between major and minor
becomes inapplicable, instead both bump the most significant component:
- major: `0.1` -> `>=0.1,<0.2`
- major: `0.0.1` -> `>=0.0.1,<0.0.2`
- major: `0.0.1.1` -> `>=0.0.1.1,<0.0.2.0`
- major: `0.0.0.1` -> `>=0.0.0.1,<0.0.0.2`
- minor: `0.1` -> `>=0.1,<0.1.1`
- minor: `0.0.1` -> `>=0.0.1,<0.0.2`
- minor: `0.0.1.1` -> `>=0.0.1.1,<0.0.2.0`
- minor: `0.0.0.1` -> `>=0.0.0.1,<0.0.0.2`

For a consistent appearance, we try to preserve the number of components
in the upper bound. For example, adding a version `2.17` with the major
option is stored as `>=2.17,<3.0`. If a version uses three components
and is greater than 0, both bounds will also use three components
(SemVer versions always have three components). Of the top 100 PyPI
packages, 8 use a non-three-component version (docutils, idna, pycparser
and soupsieve with two components, packaging, pytz and tzdata with two
component, CalVer and trove-classifiers with four component CalVer).
Example `pyproject.toml` files with the top 100 packages: [`--bounds
major`](https://gist.github.com/konstin/0aaffa9ea53c4834c22759e8865409f4)
and [`--bounds
minor`](https://gist.github.com/konstin/e77f5e990a7efe8a3c8a97c5c5b76964).
While many projects follow version scheme that roughly or directly
matches the major or minor options, these compatibility ranges are
usually not applicable for the also popular CalVer versioning.

For pre-release versions, there are two framings we could take: One is
that pre-releases generally make no guarantees about compatibility
between them and are used to introduce breaking changes, so we should
pin them exactly. In many cases however, pre-release specifiers are used
because a project needs a bugfix or a feature that hasn't made it into a
stable release, or because a project is compatible with the next version
before a final version for that release is published. In those cases,
compatibility with other packages that depend on the same library is
more important, so the desired bound is the same as it would be for the
stable release, except with the lower bound lowered to include
pre-release.

The names of the bounds and the name of the flag is up for bikeshedding.
Currently, the option is call `tool.uv.bounds`, but we could also move
it under `tool.uv.edit.bounds`, where it would be the first/only entry.

Fixes #6783

---------

Co-authored-by: Zanie Blue <[email protected]>

Author: konstin

Cargo.lock

@@ -32,6 +32,7 @@ uv-static = { workspace = true }
 uv-torch = { workspace = true, features = ["clap"] }
 uv-version = { workspace = true }
 uv-warnings = { workspace = true }
+uv-workspace = { workspace = true }
 
 anstream = { workspace = true }
 anyhow = { workspace = true }

crates/uv-cli/Cargo.toml

@@ -22,6 +22,7 @@ use uv_redacted::DisplaySafeUrl;
 use uv_resolver::{AnnotationStyle, ExcludeNewer, ForkStrategy, PrereleaseMode, ResolutionMode};
 use uv_static::EnvVars;
 use uv_torch::TorchMode;
+use uv_workspace::pyproject_mut::AddBoundsKind;
 
 pub mod comma;
 pub mod compat;
@@ -836,10 +837,6 @@ pub enum ProjectCommand {
     /// it includes markers that differ from the existing specifier in which case another entry for
     /// the dependency will be added.
     ///
-    /// If no constraint or URL is provided for a dependency, a lower bound is added equal to the
-    /// latest compatible version of the package, e.g., `>=1.2.3`, unless `--frozen` is provided, in
-    /// which case no resolution is performed.
-    ///
     /// The lockfile and project environment will be updated to reflect the added dependencies. To
     /// skip updating the lockfile, use `--frozen`. To skip updating the environment, use
     /// `--no-sync`.
@@ -3562,6 +3559,19 @@ pub struct AddArgs {
     )]
     pub raw: bool,
 
+    /// The kind of version specifier to use when adding dependencies.
+    ///
+    /// When adding a dependency to the project, if no constraint or URL is provided, a constraint
+    /// is added based on the latest compatible version of the package. By default, a lower bound
+    /// constraint is used, e.g., `>=1.2.3`.
+    ///
+    /// When `--frozen` is provided, no resolution is performed, and dependencies are always added
+    /// without constraints.
+    ///
+    /// This option is in preview and may change in any future release.
+    #[arg(long, value_enum)]
+    pub bounds: Option<AddBoundsKind>,
+
     /// Commit to use when adding a dependency from Git.
     #[arg(long, group = "git-ref", action = clap::ArgAction::Set)]
     pub rev: Option<String>,

crates/uv-cli/src/lib.rs

@@ -33,6 +33,7 @@ uv-resolver = { workspace = true, features = ["schemars", "clap"] }
 uv-static = { workspace = true }
 uv-torch = { workspace = true, features = ["schemars", "clap"] }
 uv-warnings = { workspace = true }
+uv-workspace = { workspace = true, features = ["schemars", "clap"] }
 
 clap = { workspace = true }
 fs-err = { workspace = true }

crates/uv-settings/Cargo.toml

@@ -14,6 +14,7 @@ use uv_python::{PythonDownloads, PythonPreference, PythonVersion};
 use uv_redacted::DisplaySafeUrl;
 use uv_resolver::{AnnotationStyle, ExcludeNewer, ForkStrategy, PrereleaseMode, ResolutionMode};
 use uv_torch::TorchMode;
+use uv_workspace::pyproject_mut::AddBoundsKind;
 
 use crate::{FilesystemOptions, Options, PipOptions};
 
@@ -74,6 +75,7 @@ macro_rules! impl_combine_or {
     };
 }
 
+impl_combine_or!(AddBoundsKind);
 impl_combine_or!(AnnotationStyle);
 impl_combine_or!(ExcludeNewer);
 impl_combine_or!(ExportFormat);

crates/uv-settings/src/combine.rs

@@ -20,6 +20,7 @@ use uv_redacted::DisplaySafeUrl;
 use uv_resolver::{AnnotationStyle, ExcludeNewer, ForkStrategy, PrereleaseMode, ResolutionMode};
 use uv_static::EnvVars;
 use uv_torch::TorchMode;
+use uv_workspace::pyproject_mut::AddBoundsKind;
 
 /// A `pyproject.toml` with an (optional) `[tool.uv]` section.
 #[allow(dead_code)]
@@ -53,6 +54,9 @@ pub struct Options {
     #[serde(flatten)]
     pub publish: PublishOptions,
 
+    #[serde(flatten)]
+    pub add: AddOptions,
+
     #[option_group]
     pub pip: Option<PipOptions>,
 
@@ -1841,6 +1845,10 @@ pub struct OptionsWire {
     trusted_publishing: Option<TrustedPublishing>,
     check_url: Option<IndexUrl>,
 
+    // #[serde(flatten)]
+    // add: AddOptions
+    add_bounds: Option<AddBoundsKind>,
+
     pip: Option<PipOptions>,
     cache_keys: Option<Vec<CacheKey>>,
 
@@ -1929,6 +1937,7 @@ impl From<OptionsWire> for Options {
             dev_dependencies,
             managed,
             package,
+            add_bounds: bounds,
             // Used by the build backend
             build_backend,
         } = value;
@@ -1996,6 +2005,7 @@ impl From<OptionsWire> for Options {
                 trusted_publishing,
                 check_url,
             },
+            add: AddOptions { add_bounds: bounds },
             workspace,
             sources,
             dev_dependencies,
@@ -2057,3 +2067,28 @@ pub struct PublishOptions {
     )]
     pub check_url: Option<IndexUrl>,
 }
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, CombineOptions, OptionsMetadata)]
+#[serde(rename_all = "kebab-case")]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub struct AddOptions {
+    /// The default version specifier when adding a dependency.
+    ///
+    /// When adding a dependency to the project, if no constraint or URL is provided, a constraint
+    /// is added based on the latest compatible version of the package. By default, a lower bound
+    /// constraint is used, e.g., `>=1.2.3`.
+    ///
+    /// When `--frozen` is provided, no resolution is performed, and dependencies are always added
+    /// without constraints.
+    ///
+    /// This option is in preview and may change in any future release.
+    #[option(
+        default = "\"lower\"",
+        value_type = "str",
+        example = r#"
+            add-bounds = "major"
+        "#,
+        possible_values = true
+    )]
+    pub add_bounds: Option<AddBoundsKind>,
+}

crates/uv-settings/src/settings.rs

@@ -31,6 +31,7 @@ uv-redacted = { workspace = true }
 uv-static = { workspace = true }
 uv-warnings = { workspace = true }
 
+clap = { workspace = true, optional = true }
 fs-err = { workspace = true }
 glob = { workspace = true }
 itertools = { workspace = true }