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

[zanieb]

Reading this... I wonder if we should suggest --preview to make this an error? --project . is a weird thing for someone to keep around later?

[Gankra]

Conversely --preview will enable a ton of random other things right..? Maybe that's fine though.

[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?