Expand the functionality of uv version --bump to support pre-releases (#13578)

This adds `alpha`, `beta`, `rc`, `stable`, `post`, and `dev` modes to
`uv version --bump`.

The components that `--bump` accepts are ordered as follows:

    major > minor > patch > stable > alpha > beta > rc > post > dev
    
Bumping a component "clears" all lesser component (`alpha`, `beta`, and
`rc` all overwrite each other):

* `--bump minor` on `1.2.3a4.post5.dev6` => `1.3.0`
* `--bump alpha` on `1.2.3a4.post5.dev6` => `1.2.3a5` 
* `--bump dev  ` on `1.2.3a4.post5.dev6` => `1.2.3a4.post5.dev7`

In addition, `--bump` can now be repeated. The primary motivation of
this is "bump stable version and also enter a prerelease", but it
technically lets you express other things if you want them:

* `--bump patch --bump alpha` on `1.2.3` => `1.2.4a1` ("bump patch
version and go to alpha 1")
* `--bump minor --bump patch` on `1.2.3` => `1.3.1` ("bump minor version
and got to patch 1")
* `--bump minor --bump minor` on `1.2.3` => `1.4.0` ("bump minor version
twice")

The `--bump` flags are sorted by their priority, so that you don't need
to remember the priority yourself. This ordering is the only "useful"
one that preserves every `--bump` you passed, so there's no concern
about loss of expressiveness. For instance `--bump minor --bump major`
would just be `--bump major` if we didn't sort, as the major bump clears
the minor version. The ordering of `beta` after `alpha` means `--bump
alpha --bump beta` will just result in beta 1; this is the one case
where a bump request will effectively get overwritten.

The `stable` mode "bumps to the next stable release", clearing the pre
(`alpha`, `beta`, `rc`), `dev`, and `post` components from a version
(`1.2.3a4.post5.dev6` => `1.2.3`). The choice to clear `post` here is a
bit odd, in that `1.2.3.post4` => `1.2.3` is actually a version
decrease, but I think this gives a more intuitive model (as preserving
`post5` in the previous example is definitely wrong), and also
post-releases are extremely obscure so probably no one will notice. In
the cases where this behaviour isn't useful, you probably wanted to pass
`--bump patch` or something anyway which *should* definitely clear the
`post5` (putting it another way: the only cases where `--bump stable`
has dubious behaviour is when you wanted it to do a noop, which, is a
command you could have just not written at all).

In all cases we preserve the "epoch" and "local" components of a
version, so the `7!` and `+local` in `7!1.2.3+local` will never be
modified by `--bump` (you can use the raw version set mode if you want
to touch those). The preservation of `local` is another slightly odd
choice, but it's a really obscure feature (so again it mostly won't come
up) and when it's used it seems to mostly be used for referring to
variant releases, in which case preserving it tends to be correct.

Fixes #13223

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>

docs/guides/package.md

@@ -55,6 +55,70 @@ Alternatively, `uv build <SRC>` will build the package in the specified director
     running `uv build --no-sources` to ensure that the package builds correctly when `tool.uv.sources`
     is disabled, as is the case when using other build tools, like [`pypa/build`](https://github.com/pypa/build).
 
+## Updating your version
+
+The `uv version` command provides conveniences for updating the version of your package before you
+publish it.
+[See the project docs for reading your package's version](./projects.md#managing-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
+```
+
+To preview the change without updating the `pyproject.toml`, use the `--dry-run` flag:
+
+```console
+$ uv version 2.0.0 --dry-run
+hello-world 1.0.0 => 2.0.0
+$ uv version
+hello-world 1.0.0
+```
+
+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` 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`).
+
+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
+```
+
+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 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
+hello-world 1.3.1b2 => 1.3.1
+```
+
+!!! info
+
+    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
 
 Publish your package with `uv publish`: