pex-cli: Change version format

[grihabor]

New tool upgrade script expects unified version format for tools, in this pr I change the format for pex-cli subsystem

[grihabor]

@huonw Here is a separate pr for pex-cli version format deprecation

[huonw]

This looks good in principle (thank you for the efforts to ensure we're not breaking existing users), but it'd be good to make the deprecation more vocal.

[huonw]

I think this will break anyone who's got an existing specification like:

[pex-cli]
version = "v2.33.4"
known_versions = ["v2.33.4|..."]

Because it'll decode to ExternalToolVersion(version="2.33.4", ...), but compare that "2.33.4" to version = "v2.33.4", in known_version, and thus not be found:

pants/src/python/pants/core/util_rules/external_tool.py

Lines 236 to 241 in 140c72a

	def known_version(self, plat: Platform) -> ExternalToolVersion | None:
	for known_version in self.known_versions:
	tool_version = self.decode_known_version(known_version)
	if plat.value == tool_version.platform and tool_version.version == self.version:
	return tool_version
	return None

We can likely handle this by overriding known_version too.

[huonw]

Maybe we could centralise the logic for stripping v. This'd also let us have a single sensible place for emitting a vocal deprecation warning, so that the deprecation is emphasised to users rather than just relying on release notes.

Maybe something like

from pants.base.deprecated import warn_or_error

...

def _strip_deprecated_version_prefix(version: str, option_name: str) -> str:
    if not version.startswith("v"):
        return version

    warn_or_error(
        "2.30.0.dev0",
        f"use of `v` prefix in [pex-cli].{option_name} value {version}",
        "The [pex-cli] subsystem now uses plain versions, like `2.33.4`, instead of `v2.33.4`. Remove the `v` prefix",
    )
    return version.lstrip("v")

And then call that like

self.url_template.format(version= _strip_deprecated_version_prefix (self.version, "version"), platform=platform)
...
super().decode_known_version(_strip_deprecated_version_prefix(known_version, "known_version"))

[huonw]

Ah, we often call out this sort of thing in the Python section specifically too.

So maybe this could be a really short bullet point here (e.g. "[pex-cli].version and known_versions should no longer include a v prefix") to make it easier to skim (if/when we have more), and then have this longer content in the Python section.

[huonw]

Thanks for the contribution. We've just branched for 2.26, so merging this pull request now will come out in 2.27, please move the release notes updates to docs/notes/2.27.x.md.