Improve the error message when running cargo add cubing @v0.5.0

[lgarron]

This has now been rescoped to providing a good error message if a v prefix is present, see #12331 (comment)

---

Problem

I keep doing something the following:

cargo add cubing@v0.5.0

This causes the following error:

error: invalid version requirement `v0.5.0`

Caused by:
  unexpected character 'v' while parsing major version number

I do this because I have a strong habit of prefixing my version numbers with v where possible, as vX.Y.Z tends to be a more unmistakable way to specify a version. And although it is not universal, it is also very common to prefix project release tags with v — to the point that the canonical cargo test for for a tag dependency even uses a value like this: https://github.com/rust-lang/cargo/blob/5b377cece0e0dd0af686cf53ce4637d5d85c2a10/tests/testsuite/cargo_add/git_tag/mod.rs#L22C1-L22C1
(I know that doesn't have a semantic meaning in this case, but it illustrates how widespread it is to indicate a version using a prefix of v.)

Further, other tools like npm allow a prefix of v (e.g. npm install cubing@v0.38.1), which is an inconsistency that causes a small stumbling block when working with multiple web technologies.

Proposed Solution

In order of preference:

• Accept an extra v before a semantic version number.
• Recognize the extra v and provide a helpful error message that includes something like: If you want to install a specific version, please run: cargo add cubing@0.5.0

Notes

No response

[epage]

From the angle of prior art (see #10472)

• npm and go support a leading v
• poetry, yarn, pnpm, bundle, and pub do not

[epage]

If we supported v here, we should also evaluate whether to support it in cargo install and all commands that accept pkgid.

[epage]

Personally, I think a v being supported for cargo add would be incorrect. cargo add accepts a version requirement and not a version and we would not want to confuse that further by having a "sigil" that implies its a version. For the other commands, there would be more room for consideration with the drawback that it would make the commands more consistent in accepted syntax while adding support for @ in all commands was a drive for consistency (#10582).

[weihanglo]

cargo install --version <ver-req> also falls into the same category where cargo add is. That mean if cargo is going to support v, there will be a inconsistentcy between cargo add/cargo install and other commands. I lean towards not support such thing for consistency.

[lgarron]

It sounds like there are good reasons not to support this, as it could produce other inconsistencies.

In that case, I would advocate for the "friendly error message" in the vein that Rust is known for:

• Recognize the extra v and provide a helpful error message that includes something like: If you want to install a specific version, please run: cargo add cubing@0.5.0

[lgarron]

Personally, I think a v being supported for cargo add would be incorrect. cargo add accepts a version requirement and not a version and we would not want to confuse that further by having a "sigil" that implies its a version.

Just to note: npm also supports e.g. npm add cubing@latest. It would be similarly nice to apply the same solution as a v prefix (either support it or show a helpful message suggesting how to force an install of the latest version — particularly, a command that will pull a version even if it was just published moments ago).

[epage]

@latest is being discussed at #10741

[weihanglo]

• Recognize the extra v and provide a helpful error message that includes something like: If you want to install a specific version, please run: cargo add cubing@0.5.0

The tricky part of this error message is that the suggestion “please run: cargo add cubing@0.5.0” might not be the correct one. People run with toolchain override cargo +nightly add … could also get the same error.

If we want this, suggesting cubing@0.5.0 instead of the full command line args is preferable I guess?

[DeveloperC286]

@epage I was having this issue with install I see yank also takes a version. Is someone working on this? I am assuming you want all three commands changed at once and the behaviour across all three the same?

[epage]

Good point in updating all of them. It would be nice though maybe not required. cargo update --precise can also take a version though that is tricky because it can also be a git ref.

I am not aware of anyone else working on this.

I'd recommend

• Making each unrelated command update its own commit or even PR
• Split each change into two commits: we ask that people add a test case showing the bad behavior in its own commit (ie it will pass showing the current error message) and then the follow up commit changes the behavior and updates the test

[DeveloperC286]

@epage You were added to the PR, but I created this draft #15259. I need to tidy up the commits and implement it for install, add and version(and ensure consistency across them). However, is the draft along the lines of acceptable quality/testing?