Feedback on `cargo-upgrade` to prepare it for merging

[CAD97]

@epage

1. Distinction between cargo update and cargo upgrade may be confusing

The verbs "update" and "upgrade" can be synonymous to users. How can we clarify this?

Making up flags, I think roughly

cargo update	is	cargo upgrade --compatible --lockfile-only
cargo upgrade	is	cargo update --allow-breaking
cargo upgrade --compatible	is	cargo update --required[1]

@epage

relying on ... people's ability to revert edits

If this is used as (partial) justification for a choice, we should consider refusing to run (or perhaps just doing a --dry-run) if VCS is dirty, like how cargo publish and cargo fix do unless you --allow-dirty.

@epage

3. How do we represent "upgrade minimum compatible versions" vs "error if upgrades needed"

Currently

• Upgrade compatible minimums: --to-lockfile
• Error if upgrades needed: --locked

Idea kernel: we use --pinned to allow updating dependencies we consider pinned; why not --compatible to cause the update to chose the latest compatible?

Even more wild would be to just have --locked mean --to-lockfile. I argue that this may be coherent: cargo upgrade --locked with the normal "ignore compatible" rules is contradictory, since you're saying "upgrade my dependencies but don't change what dependencies I'm using."

This kinda feels like the difference between --frozen and --locked to me, though perhaps only inasmuch as I don't really understand the difference between them. upgrade imho should semantically include updating the lockfile to the upgraded version (cargo update -p upgraded...), so --to-lockfile is as much as it can do without editing the lockfile or accessing the network (--offline?).

I admit not fully understanding what --frozen adds to --locked (--offline just for version resolution, perhaps?) but it does feel similar to what's desired as it's more locked than --locked.

@epage

There is --dry-run but there are multiple, valid, approaches to error reporting for that

• Error only if a non-dry-run will fail
• Error if the --dry-run was prevented from doing something
• Always error

When does cargo publish --dry-run error? Answer: if publishing would fail before upload; it ends with a warning: aborted upload due to dry run and a 0 exit code. Following that example, cargo upgrade --dry-run should exit with the same exit code as a non-dry-run if everything succeeded except for skipped changes to the manifest(s)/lockfile.

If verifying no change is considered necessary to support (question: is it?), e.g. cargo upgrade --verify-unchanged is a reasonable way of explicitly requesting this.

@epage

A more out there alternative to --to-lockfile is we actually prompt the user for each upgrade and have a --choice <none|locked|latest> to bypass the prompts with a specific choice.

--interactive is a great mode to have available, but it probably should be opt-in since none of the other builtin cargo subcommands are interactive by default.

@epage

=3.1 will still allow upgrading to patch releases.

Updating, yes, but upgrade --pinned without --to-lockfile will only see compatible versions, and with --to-lockfile you're still not changing the manifest's precision, so the only thing that would change is the lockfile (which doesn't with --to-lockfile; you'd need --compatible.)

---

1. Updates to the lockfile are "optional," as the lockfile is ignored by default for libraries (default VCS ignore ignores the lockfile), always for dependencies, and when using cargo install (unless you use --locked; we should invert this imho). Updates to the manifest are "required" for any downstream user to provide, since you've upgraded your dependency version specification/requirement. ↩︎