Skip to content

Commit

Permalink
Auto merge of #14047 - epage:breaking, r=weihanglo
Browse files Browse the repository at this point in the history
docs: Iterate on --breaking docs

This is a follow up to #13979 to try to clarify things in prep for users testing this.
  • Loading branch information
bors committed Jun 12, 2024
2 parents 4dcbca1 + 6bd7623 commit 30e5580
Show file tree
Hide file tree
Showing 7 changed files with 101 additions and 12 deletions.
2 changes: 1 addition & 1 deletion src/bin/cargo/commands/update.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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'),
)
Expand Down
17 changes: 17 additions & 0 deletions src/doc/man/cargo-update.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/rust-lang/cargo/issues/12425> 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
Expand Down
21 changes: 21 additions & 0 deletions src/doc/man/generated_txt/cargo-update.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
<https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> 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 are updated only if they don’t already exist in the
Expand Down
16 changes: 16 additions & 0 deletions src/doc/src/commands/cargo-update.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,22 @@ from the maintainers of the package.</p>
requirement in <code>Cargo.toml</code> doesn’t contain any pre-release identifier (nightly only).</dd>


<dt class="option-term" id="option-cargo-update---breaking"><a class="option-anchor" href="#option-cargo-update---breaking"></a><code>--breaking</code> <em>directory</em></dt>
<dd class="option-desc">Update <em>spec</em> to latest SemVer-breaking version.</p>
<p>Version requirements will be modified to allow this update.</p>
<p>This only applies to dependencies when</p>
<ul>
<li>The package is a dependency of a workspace member</li>
<li>The dependency is not renamed</li>
<li>A SemVer-incompatible version is available</li>
<li>The “SemVer operator” is used (<code>^</code> which is the default)</li>
</ul>
<p>This option is unstable and available only on the
<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a>
and requires the <code>-Z unstable-options</code> flag to enable.
See <a href="https://github.com/rust-lang/cargo/issues/12425">https://github.com/rust-lang/cargo/issues/12425</a> for more information.</dd>


<dt class="option-term" id="option-cargo-update--w"><a class="option-anchor" href="#option-cargo-update--w"></a><code>-w</code></dt>
<dt class="option-term" id="option-cargo-update---workspace"><a class="option-anchor" href="#option-cargo-update---workspace"></a><code>--workspace</code></dt>
<dd class="option-desc">Attempt to update only packages defined in the workspace. Other packages
Expand Down
25 changes: 15 additions & 10 deletions src/doc/src/reference/unstable.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: <https://github.com/rust-lang/wg-cargo-std-aware>

Expand Down
30 changes: 30 additions & 0 deletions src/etc/man/cargo-update.1
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
and requires the \fB\-Z unstable\-options\fR flag to enable.
See <https://github.com/rust\-lang/cargo/issues/12425> for more information.
.RE
.sp
\fB\-w\fR,
\fB\-\-workspace\fR
.RS 4
Expand Down
2 changes: 1 addition & 1 deletion tests/testsuite/cargo_update/help/stdout.term.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 30e5580

Please sign in to comment.