Auto merge of #11862 - weihanglo:doc-yank, r=<try>

doc: clarify implications of `cargo-yank`

### What does this PR try to resolve?

I found the documentation for `cargo yank` was not especially clear on the implications of yanking a crate, and I have seen this causing confusion within the community - tafia/quick-xml#475.

On a somewhat related note, I have been observing lots more crates getting yanked recently and this is resulting in a fair amount of dependency upgrade busywork. I think/hope part of this is a documentation issue.

src/doc/man/cargo-yank.md

@@ -15,16 +15,63 @@ The yank command removes a previously published crate's version from the
 server's index. This command does not delete any data, and the crate will
 still be available for download via the registry's download link.
 
-Note that existing crates locked to a yanked version will still be able to
-download the yanked version to use it. Cargo will, however, not allow any new
-crates to be locked to any yanked version.
+Cargo will not use a yanked version for any new project or checkout without a
+pre-existing lockfile, and will generate an error if there are no longer
+any compatible versions for your crate.
 
 This command requires you to be authenticated with either the `--token` option
 or using {{man "cargo-login" 1}}.
 
 If the crate name is not specified, it will use the package name from the
 current directory.
 
+### How yank works
+
+For example, the `foo` crate published version `1.5.0` and another crate `bar`
+declared a dependency on version `foo = "1.5"`. Now `foo` releases a new, but
+not semver compatible, version `2.0.0`, and finds a critical issue with `1.5.0`.
+If `1.5.0` is yanked, no new project or checkout without an existing lockfile
+will be able to use crate `bar` as it relies on `1.5`.
+
+In this case, the maintainers of `foo` should first publish a semver compatible
+version such as `1.5.1` prior to yanking `1.5.0` so that `bar` and all projects
+that depend on `bar` will continue to work.
+
+As another example, consider a crate `bar` with published versions `1.5.0`,
+`1.5.1`, `1.5.2`, `2.0.0` and `3.0.0`. The following table identifies the
+versions cargo could use in the absence of a lockfile for different SemVer
+requirements, following a given release being yanked:
+
+| Yanked Version / SemVer requirement | `bar = "1.5.0"`                         | `bar = "=1.5.0"` | `bar = "2.0.0"`  |
+|-------------------------------------|-----------------------------------------|------------------|------------------|
+| `1.5.0`                             | Use either `1.5.1` or `1.5.2`           | **Return Error** | Use `2.0.0`      |
+| `1.5.1`                             | Use either `1.5.0` or `1.5.2`           | Use `1.5.0`      | Use `2.0.0`      |
+| `2.0.0`                             | Use either `1.5.0`, `1.5.1` or `0.22.2` | Use `1.5.0`      | **Return Error** |
+
+### When to yank
+
+Crates should only be yanked in exceptional circumstances, for example, an
+accidental publish, an unintentional SemVer breakages, or a significantly
+broken and unusable crate. In the case of security vulnerabilities, [RustSec]
+is typically a less disruptive mechanism to inform users and encourage them
+to upgrade, and avoids the possibility of significant downstream disruption
+irrespective of susceptibility to the vulnerability in question.
+
+A common workflow is to yank a crate having already published a semver
+compatible version, to reduce the probability of preventing dependent
+crates from compiling.
+
+To address copyright, licensing, or personal data issues with your published
+crate, contact the maintainers of the registry you used. For crates.io, refer
+to their [policies] and contact them at <help@crates.io>.
+
+If your credentials have been leaked, the recommended process is to revoke them
+immediately. Once a crate is published, it's impossible to know if those leaked
+credentials have been copied, so taking swift action is crucial.
+
+[RustSec]: https://rustsec.org/
+[policies]: https://crates.io/policies
+
 ## OPTIONS
 
 ### Yank Options

src/doc/man/generated_txt/cargo-yank.txt

@@ -13,16 +13,69 @@ DESCRIPTION
        crate will still be available for download via the registry’s download
        link.
 
-       Note that existing crates locked to a yanked version will still be able
-       to download the yanked version to use it. Cargo will, however, not allow
-       any new crates to be locked to any yanked version.
+       Cargo will not use a yanked version for any new project or checkout
+       without a pre-existing lockfile, and will generate an error if there are
+       no longer any compatible versions for your crate.
 
        This command requires you to be authenticated with either the --token
        option or using cargo-login(1).
 
        If the crate name is not specified, it will use the package name from
        the current directory.
 
+   How yank works
+       For example, the foo crate published version 1.5.0 and another crate bar
+       declared a dependency on version foo = "1.5". Now foo releases a new,
+       but not semver compatible, version 2.0.0, and finds a critical issue
+       with 1.5.0. If 1.5.0 is yanked, no new project or checkout without an
+       existing lockfile will be able to use crate bar as it relies on 1.5.
+
+       In this case, the maintainers of foo should first publish a semver
+       compatible version such as 1.5.1 prior to yanking 1.5.0 so that bar and
+       all projects that depend on bar will continue to work.
+
+       As another example, consider a crate bar with published versions 1.5.0,
+       1.5.1, 1.5.2, 2.0.0 and 3.0.0. The following table identifies the
+       versions cargo could use in the absence of a lockfile for different
+       SemVer requirements, following a given release being yanked:
+
+       +------------------------+----------------------+----------+----------+
+       | Yanked Version /       | bar = "1.5.0"        | bar =    | bar =    |
+       | SemVer requirement     |                      | "=1.5.0" | "2.0.0"  |
+       +------------------------+----------------------+----------+----------+
+       | 1.5.0                  | Use either 1.5.1 or  | Return   | Use      |
+       |                        | 1.5.2                | Error    | 2.0.0    |
+       +------------------------+----------------------+----------+----------+
+       | 1.5.1                  | Use either 1.5.0 or  | Use      | Use      |
+       |                        | 1.5.2                | 1.5.0    | 2.0.0    |
+       +------------------------+----------------------+----------+----------+
+       | 2.0.0                  | Use either 1.5.0,    | Use      | Return   |
+       |                        | 1.5.1 or 0.22.2      | 1.5.0    | Error    |
+       +------------------------+----------------------+----------+----------+
+
+   When to yank
+       Crates should only be yanked in exceptional circumstances, for example,
+       an accidental publish, an unintentional SemVer breakages, or a
+       significantly broken and unusable crate. In the case of security
+       vulnerabilities, RustSec <https://rustsec.org/> is typically a less
+       disruptive mechanism to inform users and encourage them to upgrade, and
+       avoids the possibility of significant downstream disruption irrespective
+       of susceptibility to the vulnerability in question.
+
+       A common workflow is to yank a crate having already published a semver
+       compatible version, to reduce the probability of preventing dependent
+       crates from compiling.
+
+       To address copyright, licensing, or personal data issues with your
+       published crate, contact the maintainers of the registry you used. For
+       crates.io, refer to their policies <https://crates.io/policies> and
+       contact them at <help@crates.io>.
+
+       If your credentials have been leaked, the recommended process is to
+       revoke them immediately. Once a crate is published, it’s impossible to
+       know if those leaked credentials have been copied, so taking swift
+       action is crucial.
+
 OPTIONS
    Yank Options
        --vers version, --version version

src/doc/src/commands/cargo-yank.md

@@ -15,16 +15,63 @@ The yank command removes a previously published crate's version from the
 server's index. This command does not delete any data, and the crate will
 still be available for download via the registry's download link.
 
-Note that existing crates locked to a yanked version will still be able to
-download the yanked version to use it. Cargo will, however, not allow any new
-crates to be locked to any yanked version.
+Cargo will not use a yanked version for any new project or checkout without a
+pre-existing lockfile, and will generate an error if there are no longer
+any compatible versions for your crate.
 
 This command requires you to be authenticated with either the `--token` option
 or using [cargo-login(1)](cargo-login.html).
 
 If the crate name is not specified, it will use the package name from the
 current directory.
 
+### How yank works
+
+For example, the `foo` crate published version `1.5.0` and another crate `bar`
+declared a dependency on version `foo = "1.5"`. Now `foo` releases a new, but
+not semver compatible, version `2.0.0`, and finds a critical issue with `1.5.0`.
+If `1.5.0` is yanked, no new project or checkout without an existing lockfile
+will be able to use crate `bar` as it relies on `1.5`.
+
+In this case, the maintainers of `foo` should first publish a semver compatible
+version such as `1.5.1` prior to yanking `1.5.0` so that `bar` and all projects
+that depend on `bar` will continue to work.
+
+As another example, consider a crate `bar` with published versions `1.5.0`,
+`1.5.1`, `1.5.2`, `2.0.0` and `3.0.0`. The following table identifies the
+versions cargo could use in the absence of a lockfile for different SemVer
+requirements, following a given release being yanked:
+
+| Yanked Version / SemVer requirement | `bar = "1.5.0"`                         | `bar = "=1.5.0"` | `bar = "2.0.0"`  |
+|-------------------------------------|-----------------------------------------|------------------|------------------|
+| `1.5.0`                             | Use either `1.5.1` or `1.5.2`           | **Return Error** | Use `2.0.0`      |
+| `1.5.1`                             | Use either `1.5.0` or `1.5.2`           | Use `1.5.0`      | Use `2.0.0`      |
+| `2.0.0`                             | Use either `1.5.0`, `1.5.1` or `0.22.2` | Use `1.5.0`      | **Return Error** |
+
+### When to yank
+
+Crates should only be yanked in exceptional circumstances, for example, an
+accidental publish, an unintentional SemVer breakages, or a significantly
+broken and unusable crate. In the case of security vulnerabilities, [RustSec]
+is typically a less disruptive mechanism to inform users and encourage them
+to upgrade, and avoids the possibility of significant downstream disruption
+irrespective of susceptibility to the vulnerability in question.
+
+A common workflow is to yank a crate having already published a semver
+compatible version, to reduce the probability of preventing dependent
+crates from compiling.
+
+To address copyright, licensing, or personal data issues with your published
+crate, contact the maintainers of the registry you used. For crates.io, refer
+to their [policies] and contact them at <help@crates.io>.
+
+If your credentials have been leaked, the recommended process is to revoke them
+immediately. Once a crate is published, it's impossible to know if those leaked
+credentials have been copied, so taking swift action is crucial.
+
+[RustSec]: https://rustsec.org/
+[policies]: https://crates.io/policies
+
 ## OPTIONS
 
 ### Yank Options

src/etc/man/cargo-yank.1

@@ -14,15 +14,91 @@ The yank command removes a previously published crate\[cq]s version from the
 server\[cq]s index. This command does not delete any data, and the crate will
 still be available for download via the registry\[cq]s download link.
 .sp
-Note that existing crates locked to a yanked version will still be able to
-download the yanked version to use it. Cargo will, however, not allow any new
-crates to be locked to any yanked version.
+Cargo will not use a yanked version for any new project or checkout without a
+pre\-existing lockfile, and will generate an error if there are no longer
+any compatible versions for your crate.
 .sp
 This command requires you to be authenticated with either the \fB\-\-token\fR option
 or using \fBcargo\-login\fR(1).
 .sp
 If the crate name is not specified, it will use the package name from the
 current directory.
+.SS "How yank works"
+For example, the \fBfoo\fR crate published version \fB1.5.0\fR and another crate \fBbar\fR
+declared a dependency on version \fBfoo = "1.5"\fR\&. Now \fBfoo\fR releases a new, but
+not semver compatible, version \fB2.0.0\fR, and finds a critical issue with \fB1.5.0\fR\&.
+If \fB1.5.0\fR is yanked, no new project or checkout without an existing lockfile
+will be able to use crate \fBbar\fR as it relies on \fB1.5\fR\&.
+.sp
+In this case, the maintainers of \fBfoo\fR should first publish a semver compatible
+version such as \fB1.5.1\fR prior to yanking \fB1.5.0\fR so that \fBbar\fR and all projects
+that depend on \fBbar\fR will continue to work.
+.sp
+As another example, consider a crate \fBbar\fR with published versions \fB1.5.0\fR,
+\fB1.5.1\fR, \fB1.5.2\fR, \fB2.0.0\fR and \fB3.0.0\fR\&. The following table identifies the
+versions cargo could use in the absence of a lockfile for different SemVer
+requirements, following a given release being yanked:
+
+.TS
+allbox tab(:);
+lt lt lt lt.
+T{
+Yanked Version / SemVer requirement
+T}:T{
+\fBbar = "1.5.0"\fR
+T}:T{
+\fBbar = "=1.5.0"\fR
+T}:T{
+\fBbar = "2.0.0"\fR
+T}
+T{
+\fB1.5.0\fR
+T}:T{
+Use either \fB1.5.1\fR or \fB1.5.2\fR
+T}:T{
+\fBReturn Error\fR
+T}:T{
+Use \fB2.0.0\fR
+T}
+T{
+\fB1.5.1\fR
+T}:T{
+Use either \fB1.5.0\fR or \fB1.5.2\fR
+T}:T{
+Use \fB1.5.0\fR
+T}:T{
+Use \fB2.0.0\fR
+T}
+T{
+\fB2.0.0\fR
+T}:T{
+Use either \fB1.5.0\fR, \fB1.5.1\fR or \fB0.22.2\fR
+T}:T{
+Use \fB1.5.0\fR
+T}:T{
+\fBReturn Error\fR
+T}
+.TE
+.sp
+.SS "When to yank"
+Crates should only be yanked in exceptional circumstances, for example, an
+accidental publish, an unintentional SemVer breakages, or a significantly
+broken and unusable crate. In the case of security vulnerabilities, \fIRustSec\fR <https://rustsec.org/>
+is typically a less disruptive mechanism to inform users and encourage them
+to upgrade, and avoids the possibility of significant downstream disruption
+irrespective of susceptibility to the vulnerability in question.
+.sp
+A common workflow is to yank a crate having already published a semver
+compatible version, to reduce the probability of preventing dependent
+crates from compiling.
+.sp
+To address copyright, licensing, or personal data issues with your published
+crate, contact the maintainers of the registry you used. For crates.io, refer
+to their \fIpolicies\fR <https://crates.io/policies> and contact them at <help@crates.io>\&.
+.sp
+If your credentials have been leaked, the recommended process is to revoke them
+immediately. Once a crate is published, it\[cq]s impossible to know if those leaked
+credentials have been copied, so taking swift action is crucial.
 .SH "OPTIONS"
 .SS "Yank Options"
 .sp