Merge cargo-upgrade into cargo

[epage]

A scratchpad for rust-lang/cargo#12425

Merge plan

• Resolve cargo upgrade is inconsistent with cargo #737
• Resolve Support workspace inheritance in cargo-upgrade #751
• Create merge-upgrade branch
• Refactor to match cargo's directory structure
• Refactor out of cargos ops/cargo_add/manifest.rs into a place for reuse
  • Possibilities: ops/cargo_edit or edit and make it public
• Port to cargo's internals
• Merge the command (like in feat: Import cargo-add into cargo rust-lang/cargo#10472)
• Update documentation (like in Document cargo-add rust-lang/cargo#10578)
• Update completions (like in Completion support for cargo-add rust-lang/cargo#10577)
• Update Tracking issue for RFC 1977: public & private dependencies rust-lang/rust#44663 to include
  • cargo-upgrade selecting a safe version (Option to skip upgrading direct dependencies if it would increase the number of copies to be built #445)
  • for suggesting the user bump major (cargo upgrade: Suggest increasing project's version after Semver-major upgrades #144)
• Transfer to cargo repo:
  • Can we report unmaintained and replacement status on cargo upgrade? #513
  • Idea: run migration scripts on cargo upgrade #410

Open questions

• How do we represent "fail if manifest will change" and "upgrade using lock file"
  • Currently "fail if manifest will change" is --locked and "upgrade using lock file" is --to-lockfile
  • Alt: if you squint --locked could also mean "upgrade using lock file"
  • Prompt the user for each upgrade by default but also accept --choice <none|locked|latest>

[epage]

Bugs

• cargo upgrade is inconsistent with cargo #737
• Support workspace inheritance in cargo-upgrade #751
• Explicitly upgrading a dependency that doesn't exist doesn't error #680
• cargo-upgrade should preserve constraint operator on upgrade #605
• Keep Origin Style while cargo upgrade #444
• cargo upgrade --skip-compatible rewrites Cargo.toml dependencies #569
• cargo upgrade --manifest-path only works with absolute paths #565
• cargo-upgrade fails with git error #460 (should be fixed just by porting to cargo's registry code)
• cargo-upgrade doesn't handle renames in a workspace properly #432
• cargo upgrade: Don't change crate source #408

Requests

• Can we report unmaintained and replacement status on cargo upgrade? #513
• Should we report new features on upgrade? #707
• Option to skip upgrading direct dependencies if it would increase the number of copies to be built #445
• Idea: run migration scripts on cargo upgrade #410
• cargo upgrade: Suggest increasing project's version after Semver-major upgrades #144
• Make cargo outdated part of cargo itself rust-lang/cargo#4309 feat(upgrade): Provide table view for upgrades  #753
• cargo upgrade --no-dev #553
• cargo upgrade should default to --skip-compatible #552
• cargo upgrade reports 2.0 -> 2.0.0 as an upgrade #516
• cargo upgrade should not upgrade pinned dependencies #454
• Upgrade workspace's crate version #426
• Option to mimic behaviour of cargo update --locked. #265
• Upgrade workspaces more efficiently (caching and parallelisation) #158

Uncertain

• cargo upgrade fails to "get new version" #470
• cargo upgrade stopped working for good #475

[epage]

Prior art

• poetry
  • Upgrade individual dependency via poetry add <name>@latest
  • No bulk upgrade, see Suggestion: new command to bump versions of dependencies in pyproject.toml python-poetry/poetry#461
• for yarn and pnpm, its unclear how much behavior is like cargo update vs cargo upgrade
• go get
  • Upgrade individual dependency via go get <dep>@latest
  • No bulk upgrade
• I didn't see anything for Julia, Ruby, or Dart.

[epage]

Current design

cargo-upgrade 0.8.0
Upgrade dependencies as specified in the local manifest file (i.e. Cargo.toml)

USAGE:
    cargo upgrade [OPTIONS] [DEPENDENCY]...

ARGS:
    <DEPENDENCY>...    Crates to be upgraded

OPTIONS:
        --all                     [deprecated in favor of `--workspace`]
        --allow-prerelease        Include prerelease versions when fetching from crates.io (e.g. 0.6.0-alpha')
        --dry-run                 Print changes to be made without making them
        --exclude <EXCLUDE>       Crates to exclude and not upgrade
    -h, --help                    Print help information
        --manifest-path <PATH>    Path to the manifest to upgrade
        --offline                 Run without accessing the network
    -p, --package <PKGID>         Package id of the crate to add this dependency to
        --skip-compatible         Only update a dependency if the new version is semver incompatible
        --to-lockfile             Upgrade all packages to the version in the lockfile
    -V, --version                 Print version information
        --workspace               Upgrade all packages in the workspace
    -Z <FLAG>                     Unstable (nightly-only) flags [possible values: preserve-precision]

This command differs from `cargo update`, which updates the dependency versions recorded in the local lock file (Cargo.lock).

If `<dependency>`(s) are provided, only the specified dependencies will be upgraded. The version to upgrade to for each can be specified with e.g.
`docopt@0.8.0` or `serde@>=0.9,<2.0`.

Dev, build, and all target dependencies will also be upgraded. Only dependencies from crates.io are supported. Git/path dependencies will be
ignored.

All packages in the workspace will be upgraded if the `--workspace` flag is supplied. The `--workspace` flag may be supplied in the presence of a
virtual manifest.

If the '--to-lockfile' flag is supplied, all dependencies will be upgraded to the currently locked version as recorded in the Cargo.lock file. This
flag requires that the Cargo.lock file is up-to-date. If the lock file is missing, or it needs to be updated, cargo-upgrade will exit with an
error. If the '--to-lockfile' flag is supplied then the network won't be accessed.

[epage]

--manfest-path and --package working like normal but --exclude being an opt-out for when no DEPENDENCY is specified and we select all, is odd.

[epage]

Another open question is if we should somehow integrate this into cargo update or if it should remain a distinct command. I was hoping some prior art would help clarify some decisions here but not really.

[epage]

I split out the main UX question to #737

[TCROC]

Any update on this issue @epage ? I would love to see this merged into the cargo update command. Or at least into the official cargo distribution.

[epage]

A design for a subset of the functuionality being merged into cargo update has been FCPed: rust-lang/cargo#12425