change uv version to be an interface for project version reads and edits

[Gankra]

This is a reimplementation of #7248 with a new CLI interface.

The old uv version is now uv self version (also it has gained a --short flag for parity).
The new uv version is now an interface for getting/setting the project version.

To give a modicum of support for migration, if uv version is run and we fail to find/read a pyproject.toml we will fallback to uv self version. uv version --project . prevents this fallback from being allowed.

The new API of uv version is as follows:

• pass nothing to read the project version
• pass a version to set the project version
• --bump major|minor|patch to semver-bump the project version
• --dry-run to show the result but not apply it
• --short to have the final printout contain only the final version
• --output-format json to get the final printout as json

$ uv version
myfast 0.1.0

$ uv version --bump major --dry-run
myfast 0.1.0 => 1.0.0

$ uv version 1.2.3 --dry-run
myfast 0.1.0 => 1.2.3

$ uv version 1.2.3
myfast 0.1.0 => 1.2.3

$ uv version  --short 
1.2.3

$ uv version  --output-format json 
{
  "package_name": "myfast",
  "version": "1.2.3",
  "commit_info": null
}

Fixes #6298

[zanieb]

I didn't explore this in my document because I was focused on uv version vs uv metadata as a decision, but it's sort of an open question if we should use uv project instead of uv metadata. My primary hesitation is that the existing top-level interface is project based, i.e., we have uv add which operates on the project and that uv project may make that more confusing? We also have uv add --script <name> and I don't think we're likely to add a uv script child interface? uv metadata --script <name> sort of makes sense with this and our existing design?

[Gankra]

I think i like metadata over project, yeah.

[Gankra]

Oh worth noting that this does not also support uv metadata project.version. It didn't seem terribly valuable for this minimal version of the metadata command, and we can always add that later?

[zanieb]

It didn't seem terribly valuable for this minimal version of the metadata command, and we can always add that later?

Agree

[n4z4m3]

One possible reason to use project over metadata is that pixi uses project.
Not that consistency with pixi is a major determining factor, but I thought I would mention it.

[HenriBlacksmith]

Not sure it fits in this PR, but you could add a show-bump like: https://callowayproject.github.io/bump-my-version/reference/cli/#bump-my-version-show-bump

[HenriBlacksmith]

Not sure it fits in this PR, but you could add a show-bump like: https://callowayproject.github.io/bump-my-version/reference/cli/#bump-my-version-show-bump

Actually it could just be some side effect of a --dry-run with no target maybe?

[zanieb]

Yeah that's --dry-run --short

[zanieb]

I'm sort of leaning towards transitioning uv version, given uv self version is a more sensible long-term interface there and we can avoid confusion by displaying the project package name. I'll ponder this some more though.

[samypr100]

I'm a tad more in favor of uv metadata as it naturally drives me to think about project metadata. uv version or uv self version makes me think of uv --version or uv self --version weirdly enough😆

[samypr100]

Perhaps a future thought, given feature requests like #6794 could this interface evolve towards supporting updating dependency versions in pyproject.toml as well (as it would follow semantics similar to bump) or would you still see that being part of other existing/new top-level interfaces?

[InSyncWithFoo]

I have a use case for this command: In-editor version bumping (currently this feature relies on Rye).

I like the command's design in whole. One minor annoyance is that uv metadata is a bit lengthy; I can't think of a better name though.

[rumpelsepp]

Simply meta instead of metadata perhaps?

[crimoniv]

Hi there! Just my 2 cents on this:

• This is the first release with a minimal/preliminary version.
• There's still an ongoing discussion about the (sub)command interface and naming (e.g., version vs meta vs metadata).
• Some features might be considered for future iterations (e.g., pre-release versions, calver support, git tags, custom version sources...).

Would it make sense to include a warning indicating that the command is experimental and subject to future changes? Similar to the warning that was shown with uv publish.

Printing the warning to stderr shouldn't interfere with scripted usage, and will allow to 1) defer commitment on the interface and 2) start collecting usage feedback.

[zanieb]

could this interface evolve towards supporting updating dependency versions in pyproject.toml as well (as it would follow semantics similar to bump) or would you still see that being part of other existing/new top-level interfaces?

I think we'll probably create a top-level interface for that since other dependency management commands are there, but I'm not sure yet. That design work is planned to happen soon. My thoughts about an expansion of the metadata section are mostly around editing or showing other pyproject.toml fields as well as dumping project metadata for integration with other tooling (i.e., cargo metadata).

[uglybug]

I guess I could just clone, build and test this locally, but I thought it might be easier just to ask the question: how does this cope with dynamic = ["version"]? It should gracefully refuse to bump or set the version at least. Even reading the version in this case I guess is impossible without actually building the project. So, again, it should gracefully exit. I just wouldn't want it to trample over a dynamic version if someone accidentally ran it to set a static one, I think. Maybe there is a use case there, though, if migrating from dynamic to static versioning. Just some thoughts anyway.

[Gankra]

The current implementation errors the command on all operations if the version field is not defined (which I believe would be the case if dynamic = ["version"]).

I should do a cleanup pass on the message though.

[Gankra]

Pushed up a version of uv metadata version that:

• has better error message for missing version field (i.e. if dynamic = ["version"])
• takes a superset of the flags of uv version (notably --output-format=json)
  • some minor design work here on if we want to change/update the json format (see snapshots)
• respects --project
• if search for a pyproject.toml fails, then we:
  • default: warn and run uv --version
  • if --project was passed: error

I left out the actual step of replacing the current uv version with uv metadata version (and I guess deleting uv metadata version?) to make it easier to review the diff, but I'll do that swap in a followup commit.

The existence of --output-format=json also breaks the parity between uv version and uv --version, as the latter does not respect that flag! As such to complete the migration plan I believe we must add uv self version which is just the current uv version (or I guess mess with clap and make --version respect it? but gross to have more random top-level flags...).

[Gankra]

Ok, updated the main comment and pushed up the latest changes

[Gankra]

Pushed up tweaks -- only thing not done is the --preview idea.

[Gankra]

Added the --preview change

[T-256]

This is Great ❤️
There is also an open issue in Rye about bumping to prereleases versions, Do we need to consider that in uv too?

[konstin]

I agree that we should improve the prerelease handling, usually when bumping a prerelease version is want to get to either jump to the next version of that prerelease (1.2.3a1 -> 1.2.3a2) or to the stable version of that release instead of the next release (1.2.3a2 -> 1.2.3).

[konstin]

Is there a reason to not make this a PackageName?

[Gankra]

It's a write-only format and the version was already being flattened to a String, so I kept it consistent.

[konstin]

Should we emit a commit info field when we don't query that information for the non-legacy fallback path?

[Gankra]

The current format for what is now uv self version --output-format json includes the field even if it's null, so I figured I wouldn't mess with the schema, and that it would be good to have the same schema for both commands?

[konstin]

I expect this will be confusing when someone expects to get commit_info for their package but even if it is in a git repository, we never give them a value for commit_info

[konstin]

Edge case test suggestion: 1!1a1.post1.dev1+deadbeef1 (you can drop the epoch fwiw, it's not used in the ecosystem)

[Gankra]

epoch?

[konstin]

the 1! in front, which allows switching versioning schemes

[Gankra]

Also incredible nightmare input

[Gankra]

oh my god epochs oh my god

[konstin]

any_prerelease and is_local catch this more generally. another option is to move bumping into uv_pep440 and using the VersionFull type

[Gankra]

I'm increasingly dubious that this even needs a warning...

[konstin]

Intuitively, I'd expect a stable bump that goes from prerelease to stable, and alpha, beta, rc, dev, post bump types that bump inside of pre/post-releases