Review

Author: zanieb

crates/uv-cli/src/lib.rs

@@ -533,8 +533,7 @@ pub struct VersionArgs {
 
     /// Update the project version using the given semantics
     ///
-    /// This flag can be passed multiple times to allow going to a new release and entering
-    /// a prerelease: `--bump patch --bump beta`
+    /// This flag can be passed multiple times.
     #[arg(group = "operation", long)]
     pub bump: Vec<VersionBump>,
 
@@ -615,25 +614,34 @@ pub struct VersionArgs {
 // to perform, we sort them and apply them in order, so users don't have to think too hard about it.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, clap::ValueEnum)]
 pub enum VersionBump {
-    /// Increase the major version (1.2.3 => 2.0.0)
+    /// Increase the major version (e.g., 1.2.3 => 2.0.0)
     Major,
-    /// Increase the minor version (1.2.3 => 1.3.0)
+    /// Increase the minor version (e.g., 1.2.3 => 1.3.0)
     Minor,
-    /// Increase the patch version (1.2.3 => 1.2.4)
+    /// Increase the patch version (e.g., 1.2.3 => 1.2.4)
     Patch,
-    /// Make the version stable (1.2.3b4.post5.dev6 => 1.2.3)
+    /// Move from a pre-release to stable version (e.g., 1.2.3b4.post5.dev6 => 1.2.3)
     ///
-    /// This intentionally clears `.postN` and preserves `+local`
+    /// Removes all pre-release components, but will not remove "local" components.
     Stable,
-    /// Increase the alpha version (1.2.3a4 => 1.2.3a5)
+    /// Increase the alpha version (e.g., 1.2.3a4 => 1.2.3a5)
+    ///
+    /// To move from a stable to a pre-release version, combine this with a stable component, e.g.,
+    /// for 1.2.3 => 2.0.0a1, you'd also include [`VersionBump::Major`].
     Alpha,
-    /// Increase the beta version (1.2.3b4 => 1.2.3b5)
+    /// Increase the beta version (e.g., 1.2.3b4 => 1.2.3b5)
+    ///
+    /// To move from a stable to a pre-release version, combine this with a stable component, e.g.,
+    /// for 1.2.3 => 2.0.0b1, you'd also include [`VersionBump::Major`].
     Beta,
-    /// Increase the rc version (1.2.3rc4 => 1.2.3rc5)
+    /// Increase the rc version (e.g., 1.2.3rc4 => 1.2.3rc5)
+    ///
+    /// To move from a stable to a pre-release version, combine this with a stable component, e.g.,
+    /// for 1.2.3 => 2.0.0rc1, you'd also include [`VersionBump::Major`].]
     Rc,
-    /// Increase the post version (1.2.3.post5 => 1.2.3.post6)
+    /// Increase the post version (e.g., 1.2.3.post5 => 1.2.3.post6)
     Post,
-    /// Increase the dev version (1.2.3a4.dev6 => 1.2.3.dev7)
+    /// Increase the dev version (e.g., 1.2.3a4.dev6 => 1.2.3.dev7)
     Dev,
 }
 

crates/uv/src/commands/project/version.rs

@@ -205,21 +205,26 @@ pub(crate) async fn project_version(
         // Very little reason to do "bump to stable" and then do other things,
         // even if we can make sense of it.
         if stable_count > 0 && bump.len() > 1 {
-            if let Some(component) = release_components.first() {
-                return Err(anyhow!(
-                    "`--bump stable` isn't needed if you're already passing `--bump {component}`"
-                ));
-            }
+            let components = bump
+                .iter()
+                .map(ToString::to_string)
+                .collect::<Vec<_>>()
+                .join(", ");
             return Err(anyhow!(
-                "`--bump stable` cannot be combined with any other `--bump`"
+                "`--bump stable` cannot be used with another `--bump` value, got: {components}"
             ));
         }
 
         // Very little reason to "bump to post" and then do other things,
         // how is it a post-release otherwise?
         if post_count > 0 && bump.len() > 1 {
+            let components = bump
+                .iter()
+                .map(ToString::to_string)
+                .collect::<Vec<_>>()
+                .join(", ");
             return Err(anyhow!(
-                "`--bump post` cannot be combined with any other `--bump`"
+                "`--bump post` cannot be used with another `--bump` value, got: {components}"
             ));
         }
 
@@ -228,19 +233,29 @@ pub(crate) async fn project_version(
         // `--bump major --bump major` perfect sense (1.2.3 => 3.0.0)
         // ...but it's weird and probably a mistake?
         if release_components.len() > 1 {
+            let components = release_components
+                .iter()
+                .map(ToString::to_string)
+                .collect::<Vec<_>>()
+                .join(", ");
             return Err(anyhow!(
-                "`--bump` can only take one of `major`, `minor`, `patch`"
+                "Only one release version component can be provided to `--bump`, got: {components}"
             ));
         }
 
         // `--bump alpha --bump beta` is basically completely incoherent
         // `--bump beta --bump beta` makes perfect sense (1.2.3b4 => 1.2.3b6)
         // ...but it's weird and probably a mistake?
         // `--bump beta --bump dev` makes perfect sense (1.2.3 => 1.2.3b1.dev1)
-        // ...but we want to discourage mixing `dev` with prereleases
+        // ...but we want to discourage mixing `dev` with pre-releases
         if prerelease_components.len() > 1 {
+            let components = prerelease_components
+                .iter()
+                .map(ToString::to_string)
+                .collect::<Vec<_>>()
+                .join(", ");
             return Err(anyhow!(
-                "`--bump` can only take one of `alpha`, `beta`, `rc`, `dev`"
+                "Only one pre-release version component can be provided to `--bump`, got: {components}"
             ));
         }
 
@@ -274,11 +289,11 @@ pub(crate) async fn project_version(
         if new_version <= old_version {
             if old_version.is_stable() && new_version.is_pre() {
                 return Err(anyhow!(
-                    "{old_version} => {new_version} didn't increase the version; when moving to a prerelease you also need to increase the release `--bump patch`?"
+                    "{old_version} => {new_version} didn't increase the version; when bumping to a pre-release version you also need to increase a release version component, e.g., with `--bump <major|minor|patch>`"
                 ));
             }
             return Err(anyhow!(
-                "{old_version} => {new_version} didn't increase the version"
+                "{old_version} => {new_version} didn't increase the version; provide the exact version to force an update"
             ));
         }
 

crates/uv/tests/it/version.rs

@@ -601,7 +601,7 @@ requires-python = ">=3.12"
     ----- stdout -----
 
     ----- stderr -----
-    error: `--bump post` cannot be combined with any other `--bump`
+    error: `--bump post` cannot be used with another `--bump` value, got: major, patch, alpha, minor, dev, minor, post, post
     ");
 
     let pyproject = fs_err::read_to_string(&pyproject_toml)?;
@@ -919,7 +919,7 @@ requires-python = ">=3.12"
     ----- stdout -----
 
     ----- stderr -----
-    error: 2.3.4.post6 => 2.3.4 didn't increase the version
+    error: 2.3.4.post6 => 2.3.4 didn't increase the version; provide the exact version to force an update
     ");
     Ok(())
 }
@@ -946,7 +946,7 @@ requires-python = ">=3.12"
     ----- stdout -----
 
     ----- stderr -----
-    error: 2.3.4b5 => 2.3.4a1 didn't increase the version
+    error: 2.3.4b5 => 2.3.4a1 didn't increase the version; provide the exact version to force an update
     ");
     Ok(())
 }
@@ -973,7 +973,7 @@ requires-python = ">=3.12"
     ----- stdout -----
 
     ----- stderr -----
-    error: 2.3.4 => 2.3.4a1 didn't increase the version; when moving to a prerelease you also need to increase the release `--bump patch`?
+    error: 2.3.4 => 2.3.4a1 didn't increase the version; when bumping to a pre-release version you also need to increase a release version component, e.g., with `--bump <major|minor|patch>`
     ");
     Ok(())
 }
@@ -1001,7 +1001,7 @@ requires-python = ">=3.12"
     ----- stdout -----
 
     ----- stderr -----
-    error: `--bump` can only take one of `major`, `minor`, `patch`
+    error: Only one release version component can be provided to `--bump`, got: major, major
     ");
     Ok(())
 }
@@ -1029,7 +1029,7 @@ requires-python = ">=3.12"
     ----- stdout -----
 
     ----- stderr -----
-    error: `--bump` can only take one of `alpha`, `beta`, `rc`, `dev`
+    error: Only one pre-release version component can be provided to `--bump`, got: alpha, alpha
     ");
     Ok(())
 }
@@ -1057,7 +1057,7 @@ requires-python = ">=3.12"
     ----- stdout -----
 
     ----- stderr -----
-    error: `--bump stable` isn't needed if you're already passing `--bump major`
+    error: `--bump stable` cannot be used with another `--bump` value, got: stable, major
     ");
     Ok(())
 }
@@ -1145,7 +1145,7 @@ requires-python = ">=3.12"
     ----- stdout -----
 
     ----- stderr -----
-    error: `--bump` can only take one of `alpha`, `beta`, `rc`, `dev`
+    error: Only one pre-release version component can be provided to `--bump`, got: alpha, dev
     ");
     Ok(())
 }
@@ -1203,7 +1203,7 @@ requires-python = ">=3.12"
     ----- stdout -----
 
     ----- stderr -----
-    error: `--bump post` cannot be combined with any other `--bump`
+    error: `--bump post` cannot be used with another `--bump` value, got: major, post
     ");
     Ok(())
 }

docs/concepts/projects/config.md

@@ -160,8 +160,6 @@ Setting `tool.uv.package = false` will force a project package _not_ to be built
 the project environment. uv will ignore a declared build system when interacting with the project;
 however, uv will still respect explicit attempts to build the project such as invoking `uv build`.
 
-## Project versioning
-
 ## Project environment path
 
 The `UV_PROJECT_ENVIRONMENT` environment variable can be used to configure the project virtual

docs/guides/package.md

@@ -61,14 +61,14 @@ The `uv version` command provides conveniences for updating the version of your
 publish it.
 [See the project docs for reading your package's version](./projects.md#managing-version).
 
-To set the the exact version of your package, just pass that version:
+To update to an exact version, provide it as a positional argument:
 
 ```console
 $ uv version 1.0.0
 hello-world 0.7.0 => 1.0.0
 ```
 
-If you want to preview the change without actually applying it, use the `--dry-run` flag:
+To preview the change without updating the `pyproject.toml`, use the `--dry-run` flag:
 
 ```console
 $ uv version 2.0.0 --dry-run
@@ -77,49 +77,37 @@ $ uv version
 hello-world 1.0.0
 ```
 
-If you want to change the version of a particular package, use the `--package` flag:
-
-```console
-$ uv version --package hello-world 1.2.3
-hello-world 1.0.0 => 1.2.3
-```
-
-To increase the version of your package, use the `--bump` flag:
+To increase the version of your package semantics, use the `--bump` option:
 
 ```console
 $ uv version --bump minor
 hello-world 1.2.3 => 1.3.0
 ```
 
-The `--bump` flag can be passed multiple times, and uv will run them in the following order that
-prevents bumps from clobbering eachother:
+The `--bump` option supports the following common version components: `major`, `minor`, `patch`,
+`stable`, `alpha`, `beta`, `rc`, `post`, and `dev`. When provided more than once, the components
+will be applied in order, from largest (`major`) to smallest (`dev`).
 
-```text
-    major > minor > patch > stable > alpha > beta > rc > post > dev
-```
-
-When you're on a stable version and want to start shipping prereleases, you'll want to bump the
-release and the prerelease:
+To move from a stable to pre-release version, bump one of the major, minor, or patch components in
+addition to the pre-release component:
 
 ```console
 $ uv version --bump patch --bump beta
 hello-world 1.3.0 => 1.3.1b1
+$ uv version --bump major --bump alpha
+hello-world 1.3.0 => 2.0.0a1
 ```
 
-!!! Note
-
-    If you only bump the prerelease here it will actually decrease the current version.
-    `uv version` will error if that ever happens. If you intended to do that, you can pass
-    `--allow-decreases` to disable the check.
-
-When you're on a prerelease and want to ship another, you can just bump the prerelease:
+When moving from a pre-release to a new pre-release version, just bump the relevant pre-release
+component:
 
 ```console
 uv version --bump beta
 hello-world 1.3.0b1 => 1.3.1b2
 ```
 
-When you're on a prerelease and want to ship a stable version, you can bump to stable:
+When moving from a pre-release to a stable version, the `stable` option can be used to clear the
+pre-release component:
 
 ```console
 uv version --bump stable
@@ -128,9 +116,8 @@ hello-world 1.3.1b2 => 1.3.1
 
 !!! info
 
-    By default, when `uv version` modifies your package it will lock and sync your project to
-    ensure everything sees the change. To prevent locking and syncing, pass `--frozen`. To just
-    prevent syncing, pass `--no-sync`.
+    By default, when `uv version` modifies the project it will perform a lock and sync. To
+    prevent locking and syncing, use `--frozen`, or,  to just prevent syncing, use `--no-sync`.
 
 ## Publishing your package
 

docs/guides/projects.md

@@ -163,30 +163,22 @@ details.
 ## Managing version
 
 The `uv version` command can be used to read your package's version.
-[See the publishing docs for updating your package's version](./package.md#updating-your-version).
 
-To get the version of your package, run `uv version` with no other arguments:
+To get the version of your package, run `uv version`:
 
 ```console
 $ uv version
 hello-world 0.7.0
 ```
 
-To get the version of a particular package, pass `--package`:
-
-```console
-$ uv version --package myapp
-myapp 1.2.3
-```
-
-To just get the version with no other output, pass `--short`:
+To get the version without the package name, use the `--short` option:
 
 ```console
 $ uv version --short
 0.7.0
 ```
 
-To get the version as json, pass `--output-format json`:
+To get version information in a JSON format, use the `--output-format json` option:
 
 ```console
 $ uv version --output-format json
@@ -197,6 +189,9 @@ $ uv version --output-format json
 }
 ```
 
+See the [publishing guide](./package.md#updating-your-version) for details on updating your package
+version.
+
 ## Running commands
 
 `uv run` can be used to run arbitrary scripts or commands in your project environment.

docs/reference/cli.md

@@ -787,18 +787,18 @@ uv version [OPTIONS] [VALUE]
 <p>Expects to receive either a hostname (e.g., <code>localhost</code>), a host-port pair (e.g., <code>localhost:8080</code>), or a URL (e.g., <code>https://localhost</code>).</p>
 <p>WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use <code>--allow-insecure-host</code> in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.</p>
 <p>May also be set with the <code>UV_INSECURE_HOST</code> environment variable.</p></dd><dt id="uv-version--bump"><a href="#uv-version--bump"><code>--bump</code></a> <i>bump</i></dt><dd><p>Update the project version using the given semantics</p>
-<p>This flag can be passed multiple times to allow going to a new release and entering a prerelease: <code>--bump patch --bump beta</code></p>
+<p>This flag can be passed multiple times.</p>
 <p>Possible values:</p>
 <ul>
-<li><code>major</code>:  Increase the major version (1.2.3 =&gt; 2.0.0)</li>
-<li><code>minor</code>:  Increase the minor version (1.2.3 =&gt; 1.3.0)</li>
-<li><code>patch</code>:  Increase the patch version (1.2.3 =&gt; 1.2.4)</li>
-<li><code>stable</code>:  Make the version stable (1.2.3b4.post5.dev6 =&gt; 1.2.3)</li>
-<li><code>alpha</code>:  Increase the alpha version (1.2.3a4 =&gt; 1.2.3a5)</li>
-<li><code>beta</code>:  Increase the beta version (1.2.3b4 =&gt; 1.2.3b5)</li>
-<li><code>rc</code>:  Increase the rc version (1.2.3rc4 =&gt; 1.2.3rc5)</li>
-<li><code>post</code>:  Increase the post version (1.2.3.post5 =&gt; 1.2.3.post6)</li>
-<li><code>dev</code>:  Increase the dev version (1.2.3a4.dev6 =&gt; 1.2.3.dev7)</li>
+<li><code>major</code>:  Increase the major version (e.g., 1.2.3 =&gt; 2.0.0)</li>
+<li><code>minor</code>:  Increase the minor version (e.g., 1.2.3 =&gt; 1.3.0)</li>
+<li><code>patch</code>:  Increase the patch version (e.g., 1.2.3 =&gt; 1.2.4)</li>
+<li><code>stable</code>:  Move from a pre-release to stable version (e.g., 1.2.3b4.post5.dev6 =&gt; 1.2.3)</li>
+<li><code>alpha</code>:  Increase the alpha version (e.g., 1.2.3a4 =&gt; 1.2.3a5)</li>
+<li><code>beta</code>:  Increase the beta version (e.g., 1.2.3b4 =&gt; 1.2.3b5)</li>
+<li><code>rc</code>:  Increase the rc version (e.g., 1.2.3rc4 =&gt; 1.2.3rc5)</li>
+<li><code>post</code>:  Increase the post version (e.g., 1.2.3.post5 =&gt; 1.2.3.post6)</li>
+<li><code>dev</code>:  Increase the dev version (e.g., 1.2.3a4.dev6 =&gt; 1.2.3.dev7)</li>
 </ul></dd><dt id="uv-version--cache-dir"><a href="#uv-version--cache-dir"><code>--cache-dir</code></a> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
 <p>Defaults to <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on macOS and Linux, and <code>%LOCALAPPDATA%\uv\cache</code> on Windows.</p>
 <p>To view the location of the cache directory, run <code>uv cache dir</code>.</p>