From 6bd7623ea7f9c35d95103b85769e1ed7af137308 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 11 Jun 2024 16:04:36 -0500 Subject: [PATCH] docs: Iterate on --breaking docs This is a follow up to #13979 to try to clarify things in prep for users testing this. --- src/bin/cargo/commands/update.rs | 2 +- src/doc/man/cargo-update.md | 17 +++++++++++ src/doc/man/generated_txt/cargo-update.txt | 21 +++++++++++++ src/doc/src/commands/cargo-update.md | 16 ++++++++++ src/doc/src/reference/unstable.md | 25 +++++++++------- src/etc/man/cargo-update.1 | 30 +++++++++++++++++++ .../cargo_update/help/stdout.term.svg | 2 +- 7 files changed, 101 insertions(+), 12 deletions(-) diff --git a/src/bin/cargo/commands/update.rs b/src/bin/cargo/commands/update.rs index 3369763d676..492be07c783 100644 --- a/src/bin/cargo/commands/update.rs +++ b/src/bin/cargo/commands/update.rs @@ -38,7 +38,7 @@ pub fn cli() -> Command { .arg( flag( "breaking", - "Upgrade [SPEC] to latest breaking versions, unless pinned (unstable)", + "Update [SPEC] to latest SemVer-breaking version (unstable)", ) .short('b'), ) diff --git a/src/doc/man/cargo-update.md b/src/doc/man/cargo-update.md index 3031afa5fbb..e0ad8ff5352 100644 --- a/src/doc/man/cargo-update.md +++ b/src/doc/man/cargo-update.md @@ -51,6 +51,23 @@ A compatible `pre-release` version can also be specified even when the version requirement in `Cargo.toml` doesn't contain any pre-release identifier (nightly only). {{/option}} +{{#option "`--breaking` _directory_" }} +Update _spec_ to latest SemVer-breaking version. + +Version requirements will be modified to allow this update. + +This only applies to dependencies when +- The package is a dependency of a workspace member +- The dependency is not renamed +- A SemVer-incompatible version is available +- The "SemVer operator" is used (`^` which is the default) + +This option is unstable and available only on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z unstable-options` flag to enable. +See for more information. +{{/option}} + {{#option "`-w`" "`--workspace`" }} Attempt to update only packages defined in the workspace. Other packages are updated only if they don't already exist in the lockfile. This diff --git a/src/doc/man/generated_txt/cargo-update.txt b/src/doc/man/generated_txt/cargo-update.txt index 1bcc1390f7b..1e3500481ad 100644 --- a/src/doc/man/generated_txt/cargo-update.txt +++ b/src/doc/man/generated_txt/cargo-update.txt @@ -43,6 +43,27 @@ OPTIONS version requirement in Cargo.toml doesn’t contain any pre-release identifier (nightly only). + --breaking directory + Update spec to latest SemVer-breaking version. + + Version requirements will be modified to allow this update. + + This only applies to dependencies when + + o The package is a dependency of a workspace member + + o The dependency is not renamed + + o A SemVer-incompatible version is available + + o The “SemVer operator” is used (^ which is the default) + + This option is unstable and available only on the nightly channel + and + requires the -Z unstable-options flag to enable. See + for more + information. + -w, --workspace Attempt to update only packages defined in the workspace. Other packages are updated only if they don’t already exist in the diff --git a/src/doc/src/commands/cargo-update.md b/src/doc/src/commands/cargo-update.md index 8de0bee9850..3c7eb59e7f1 100644 --- a/src/doc/src/commands/cargo-update.md +++ b/src/doc/src/commands/cargo-update.md @@ -47,6 +47,22 @@ from the maintainers of the package.

requirement in Cargo.toml doesn’t contain any pre-release identifier (nightly only). +
--breaking directory
+
Update spec to latest SemVer-breaking version.

+

Version requirements will be modified to allow this update.

+

This only applies to dependencies when

+
    +
  • The package is a dependency of a workspace member
    • +
  • The dependency is not renamed
    • +
  • A SemVer-incompatible version is available
    • +
  • The “SemVer operator” is used (^ which is the default)
    • +
+

This option is unstable and available only on the +nightly channel +and requires the -Z unstable-options flag to enable. +See https://github.com/rust-lang/cargo/issues/12425 for more information.

+ +
-w
--workspace
Attempt to update only packages defined in the workspace. Other packages diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index b9c01e58b3b..d26e03b5148 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -383,21 +383,26 @@ It would not be possible to upgrade to `0.2.0-pre.0` from `0.1.1` in the same wa * Tracking Issue: [#12425](https://github.com/rust-lang/cargo/issues/12425) -This feature allows upgrading dependencies to breaking versions with -`update --breaking`. +Allow upgrading dependencies version requirements in `Cargo.toml` across SemVer +incompatible versions using with the `--breaking` flag. -This is essentially migrating `cargo upgrade` from `cargo-edit` into Cargo itself, -and involves making changes to the `Cargo.toml` manifests, not just the lock file. +This only applies to dependencies when +- The package is a dependency of a workspace member +- The dependency is not renamed +- A SemVer-incompatible version is available +- The "SemVer operator" is used (`^` which is the default) -When doing a breaking update, Cargo will keep all non-breaking dependencies -unchanged. It will also not change any dependencies that use a different version -operator than the default caret. Also, it will not upgrade any renamed package -dependencies. Example: +Users may further restrict which packages get upgraded by specifying them on +the command line. -```sh -cargo +nightly update --breaking -Z unstable-options +Example: +```console +$ cargo +nightly -Zunstable-options update --breaking +$ cargo +nightly -Zunstable-options update --breaking clap ``` +*This is meant to fill a similar role as [cargo-upgrade](https://github.com/killercup/cargo-edit/)* + ## build-std * Tracking Repository: diff --git a/src/etc/man/cargo-update.1 b/src/etc/man/cargo-update.1 index de4770fcacb..c682e05fc40 100644 --- a/src/etc/man/cargo-update.1 +++ b/src/etc/man/cargo-update.1 @@ -48,6 +48,36 @@ A compatible \fBpre\-release\fR version can also be specified even when the vers requirement in \fBCargo.toml\fR doesn\[cq]t contain any pre\-release identifier (nightly only). .RE .sp +\fB\-\-breaking\fR \fIdirectory\fR +.RS 4 +Update \fIspec\fR to latest SemVer\-breaking version. +.sp +Version requirements will be modified to allow this update. +.sp +This only applies to dependencies when +.sp +.RS 4 +\h'-04'\(bu\h'+02'The package is a dependency of a workspace member +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'The dependency is not renamed +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'A SemVer\-incompatible version is available +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'The \[lq]SemVer operator\[rq] is used (\fB^\fR which is the default) +.RE +.sp +This option is unstable and available only on the +\fInightly channel\fR +and requires the \fB\-Z unstable\-options\fR flag to enable. +See for more information. +.RE +.sp \fB\-w\fR, \fB\-\-workspace\fR .RS 4 diff --git a/tests/testsuite/cargo_update/help/stdout.term.svg b/tests/testsuite/cargo_update/help/stdout.term.svg index 565032d8699..c1a14883b10 100644 --- a/tests/testsuite/cargo_update/help/stdout.term.svg +++ b/tests/testsuite/cargo_update/help/stdout.term.svg @@ -35,7 +35,7 @@ --precise <PRECISE> Update [SPEC] to exactly PRECISE - -b, --breaking Upgrade [SPEC] to latest breaking versions, unless pinned (unstable) + -b, --breaking Update [SPEC] to latest SemVer-breaking version (unstable) -v, --verbose... Use verbose output (-vv very verbose/build.rs output)