doc: clarify implications of cargo-yank

src/doc/man/cargo-yank.md

@@ -15,16 +15,66 @@ 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.
+
+When addressing copyright, licensing, or personal data issues with a published
+crate, simply yanking it may not suffice. In such cases, contact the maintainers
+of the registry you used. For crates.io, refer to their [policies] and contact
+them at <[email protected]>.
+
+If credentials have been leaked, the recommended course of action is to revoke
+them immediately. Once a crate has been published, it is impossible to determine
+if the leaked credentials have been copied. Yanking the crate only prevents new
+users from downloading it, but cannot stop those who have already downloaded it
+from keeping or even spreading the leaked credentials.
+
+[RustSec]: https://rustsec.org/
+[policies]: https://crates.io/policies
+
 ## OPTIONS
 
 ### Yank Options

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

@@ -13,16 +13,72 @@ 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.
+
+       When addressing copyright, licensing, or personal data issues with a
+       published crate, simply yanking it may not suffice. In such cases,
+       contact the maintainers of the registry you used. For crates.io, refer
+       to their policies <https://crates.io/policies> and contact them at
+       <[email protected]>.
+
+       If credentials have been leaked, the recommended course of action is to
+       revoke them immediately. Once a crate has been published, it is
+       impossible to determine if the leaked credentials have been copied.
+       Yanking the crate only prevents new users from downloading it, but
+       cannot stop those who have already downloaded it from keeping or even
+       spreading the leaked credentials.
+
 OPTIONS
    Yank Options
        --vers version, --version version

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

@@ -15,16 +15,66 @@ 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.
+
+When addressing copyright, licensing, or personal data issues with a published
+crate, simply yanking it may not suffice. In such cases, contact the maintainers
+of the registry you used. For crates.io, refer to their [policies] and contact
+them at <[email protected]>.
+
+If credentials have been leaked, the recommended course of action is to revoke
+them immediately. Once a crate has been published, it is impossible to determine
+if the leaked credentials have been copied. Yanking the crate only prevents new
+users from downloading it, but cannot stop those who have already downloaded it
+from keeping or even spreading the leaked credentials.
+
+[RustSec]: https://rustsec.org/
+[policies]: https://crates.io/policies
+
 ## OPTIONS
 
 ### Yank Options

src/etc/man/cargo-yank.1

@@ -14,15 +14,94 @@ 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
+When addressing copyright, licensing, or personal data issues with a published
+crate, simply yanking it may not suffice. In such cases, contact the maintainers
+of the registry you used. For crates.io, refer to their \fIpolicies\fR <https://crates.io/policies> and contact
+them at <[email protected]>\&.
+.sp
+If credentials have been leaked, the recommended course of action is to revoke
+them immediately. Once a crate has been published, it is impossible to determine
+if the leaked credentials have been copied. Yanking the crate only prevents new
+users from downloading it, but cannot stop those who have already downloaded it
+from keeping or even spreading the leaked credentials.
 .SH "OPTIONS"
 .SS "Yank Options"
 .sp