Expand the functionality of uv version --bump to support pre-releases

[Gankra]

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

[Gankra]

These chunks of the PR should ideally cover any corner case you might want to ask about.

[Gankra]

"Did you consider a --bump pre mode" -- yes I don't think it's worth the API space, it seems reasonable to ask a user to know what flavour of prerelease they're using (and if I'm wrong we can add it later).

[Gankra]

For the sake of getting an intrusive thought out of my head: there are several times where I said "maybe you should be able to express --bump minor --bump alpha in a way where the alpha doesn't get reset" (e.g. 1.2.3a4 => 1.3.0a5) before reminding myself that this makes absolutely no semantic sense (so no we're not supporting that).

[konstin]

Currently, there can be negative version bumps, where bumping 0.1.0b1 with uv version --bump alpha lowers the version instead of increasing it, as this isn't the next alpha but the previous alpha before the beta.

[konstin]

The code looks good, but I'm concerned by how easy it is to decrease the version accidentally, the version is decreased when using a prerelease bump on stable version by default.

[Gankra]

I've pushed up a separate commit that adds an --allow-decreases flag, and made the code error if a series of bumps fails to increase the version, as well as tests for the 3 cases I know of where this can happen.

[Gankra]

Updated cli docs a bit

[BurntSushi]

Nice work!!! I wish this was in Cargo. :-)

[BurntSushi]

I might mention here that this could decrease the version number, and therefore, it's common to use this in conjunction with another --bump flag like --bump patch.

[zanieb]

Interesting. I presume there was discussion on this, but I'm on my phone so just want to flag it. Why is the patch bump needed too? We fail without it?

(I'll also just read the rest of the pull request when I'm home)

[zanieb]

I would say "it would decrease the current version" not "it will" if you're going to error.

[Xemnas0]

Would it be possible to include a functionality of bumping the version in certain files, like commitizen does? It also allows to look for what lines to change according to a per-file regex

[Gankra]

Would it be possible to include a functionality of bumping the version in certain files, like commitizen does? It also allows to look for what lines to change according to a per-file regex

I've certainly always found those kinds of features useful in similar commands, although it would require non-trivial design work we're definitely not doing in this PR.

[VedankPurohit]

When will this be merged?

[zanieb]

When it's done — we're a small team balancing a lot of work!

[97k]

Hey @zanieb @Gankra , just checking in - do we have any ETA on this getting merged?
We've been managing dev versions manually for now, and this feature would really streamline our workflow. Totally understand you're a small team and appreciate all the work you're putting into this!

[tmke8]

I wonder if it wouldn't have been better to introduce a new argument instead of allowing repeated --bump. It seems that the only realistic use case here combines one "stable" bump and one "unstable" bump. So, one could have a --pre-bump flag and write the example in the PR description like this:

• --bump patch --pre-bump alpha on 1.2.3 => 1.2.4a1 ("bump patch version and go to alpha 1")

And this would result in an error:

• --bump minor --bump patch

This would remove confusing behavior such as

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.

--pre-bump would allow alpha, beta, rc, dev, and post as argument.

Instead of --bump stable, I think something like --clear-suffixes would be clearer, which then also makes the --allow-decreases flag unnecessary, because the name --clear-suffixes doesn't imply an increase in the version, so the user won't be surprised when --clear-suffixes decreases the version (which it always does, I think). --clear-suffixes would be permitted to be used in combination with --bump but not with --pre-bump (because that makes no sense. EDIT: actually, --clear-suffixes should not be combined with any bumps; the stable bumps imply this already.

EDIT2: one problem with the name "pre-bump" is that .post is not actually a pre-release. Another option might be --bump-suffix.

[zanieb]

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.

We just ban this now.

which then also makes the --allow-decreases flag unnecessary

We removed this, it's not worth the complexity.

[tmke8]

Okay, that doesn't sound too bad then. It just seems to me that this commandline interface is "too weakly typed" in the sense that the "signature" seems to allow many things that will actually give a runtime error.

[zanieb]

I think the things that will give a runtime error are pretty weird for a user to do though, wouldn't you think?

[tmke8]

That's a good point, yes.