Clarify Implications of Cargo Yank

src/doc/man/cargo-yank.md

@@ -15,9 +15,39 @@ 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.
+Crates should only be yanked in exceptional circumstances, for example, license/copyright issues, accidental
+inclusion of [PII](https://en.wikipedia.org/wiki/Personal_data), credentials, etc... 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.
+
+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.
+
+For example, the `foo` crate published version `0.22.0` and another crate `bar`
+declared a dependency on version `foo = 0.22`. Now `foo` releases a new, but
+not semver compatible, version `0.23.0`, and finds a critical issue with `0.22.0`.
+If `0.22.0` is yanked, no new project or checkout without an existing lockfile will be
+able to use crate `bar` as it relies on `0.22`.
+
+In this case, the maintainers of `foo` should first publish a semver compatible version
+such as `0.22.1` prior to yanking `0.22.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 `0.22.0`, `0.22.1`, 
+`0.22.2`, `0.23.0` and `0.24.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 = "0.22.0"`                          | `bar = "=0.22.0"` | `bar = "0.23.0"` |
+|-------------------------------------|-------------------------------------------|-------------------|------------------|
+| `0.22.0`                            | Use either `0.22.1` or `0.22.2`           | **Return Error**  | Use `0.23.0`     |
+| `0.22.1`                            | Use either `0.22.0` or `0.22.2`           | Use `0.22.0`      | Use `0.23.0`     |
+| `0.23.0`                            | Use either `0.22.0`, `0.21.0` or `0.22.2` | Use `0.22.0`      | **Return Error** |
+
+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.
 
 This command requires you to be authenticated with either the `--token` option
 or using {{man "cargo-login" 1}}.

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

@@ -12,9 +12,51 @@ DESCRIPTION
        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.
+       Crates should only be yanked in exceptional circumstances, for example,
+       license/copyright issues, accidental inclusion of PII
+       <https://en.wikipedia.org/wiki/Personal_data>, credentials, etc... 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.
+
+       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.
+
+       For example, the foo crate published version 0.22.0 and another crate
+       bar declared a dependency on version foo = 0.22. Now foo releases a new,
+       but not semver compatible, version 0.23.0, and finds a critical issue
+       with 0.22.0. If 0.22.0 is yanked, no new project or checkout without an
+       existing lockfile will be able to use crate bar as it relies on 0.22.
+
+       In this case, the maintainers of foo should first publish a semver
+       compatible version such as 0.22.1 prior to yanking 0.22.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 0.22.0,
+       0.22.1, 0.22.2, 0.23.0 and 0.24.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 = "0.22.0"        | bar =     | bar =    |
+       | SemVer requirement    |                       | "=0.22.0" | "0.23.0" |
+       +-----------------------+-----------------------+-----------+----------+
+       | 0.22.0                | Use either 0.22.1 or  | Return    | Use      |
+       |                       | 0.22.2                | Error     | 0.23.0   |
+       +-----------------------+-----------------------+-----------+----------+
+       | 0.22.1                | Use either 0.22.0 or  | Use       | Use      |
+       |                       | 0.22.2                | 0.22.0    | 0.23.0   |
+       +-----------------------+-----------------------+-----------+----------+
+       | 0.23.0                | Use either 0.22.0,    | Use       | Return   |
+       |                       | 0.21.0 or 0.22.2      | 0.22.0    | Error    |
+       +-----------------------+-----------------------+-----------+----------+
+
+       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.
 
        This command requires you to be authenticated with either the --token
        option or using cargo-login(1).

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

@@ -15,9 +15,39 @@ 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.
+Crates should only be yanked in exceptional circumstances, for example, license/copyright issues, accidental
+inclusion of [PII](https://en.wikipedia.org/wiki/Personal_data), credentials, etc... 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.
+
+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.
+
+For example, the `foo` crate published version `0.22.0` and another crate `bar`
+declared a dependency on version `foo = 0.22`. Now `foo` releases a new, but
+not semver compatible, version `0.23.0`, and finds a critical issue with `0.22.0`.
+If `0.22.0` is yanked, no new project or checkout without an existing lockfile will be
+able to use crate `bar` as it relies on `0.22`.
+
+In this case, the maintainers of `foo` should first publish a semver compatible version
+such as `0.22.1` prior to yanking `0.22.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 `0.22.0`, `0.22.1`, 
+`0.22.2`, `0.23.0` and `0.24.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 = "0.22.0"`                          | `bar = "=0.22.0"` | `bar = "0.23.0"` |
+|-------------------------------------|-------------------------------------------|-------------------|------------------|
+| `0.22.0`                            | Use either `0.22.1` or `0.22.2`           | **Return Error**  | Use `0.23.0`     |
+| `0.22.1`                            | Use either `0.22.0` or `0.22.2`           | Use `0.22.0`      | Use `0.23.0`     |
+| `0.23.0`                            | Use either `0.22.0`, `0.21.0` or `0.22.2` | Use `0.22.0`      | **Return Error** |
+
+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.
 
 This command requires you to be authenticated with either the `--token` option
 or using [cargo-login(1)](cargo-login.html).

src/etc/man/cargo-yank.1

@@ -14,9 +14,75 @@ 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.
 .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.
+Crates should only be yanked in exceptional circumstances, for example, license/copyright issues, accidental
+inclusion of \fIPII\fR <https://en.wikipedia.org/wiki/Personal_data>, credentials, etc... 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
+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
+For example, the \fBfoo\fR crate published version \fB0.22.0\fR and another crate \fBbar\fR
+declared a dependency on version \fBfoo = 0.22\fR\&. Now \fBfoo\fR releases a new, but
+not semver compatible, version \fB0.23.0\fR, and finds a critical issue with \fB0.22.0\fR\&.
+If \fB0.22.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 \fB0.22\fR\&.
+.sp
+In this case, the maintainers of \fBfoo\fR should first publish a semver compatible version
+such as \fB0.22.1\fR prior to yanking \fB0.22.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 \fB0.22.0\fR, \fB0.22.1\fR, 
+\fB0.22.2\fR, \fB0.23.0\fR and \fB0.24.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 = "0.22.0"\fR
+T}:T{
+\fBbar = "=0.22.0"\fR
+T}:T{
+\fBbar = "0.23.0"\fR
+T}
+T{
+\fB0.22.0\fR
+T}:T{
+Use either \fB0.22.1\fR or \fB0.22.2\fR
+T}:T{
+\fBReturn Error\fR
+T}:T{
+Use \fB0.23.0\fR
+T}
+T{
+\fB0.22.1\fR
+T}:T{
+Use either \fB0.22.0\fR or \fB0.22.2\fR
+T}:T{
+Use \fB0.22.0\fR
+T}:T{
+Use \fB0.23.0\fR
+T}
+T{
+\fB0.23.0\fR
+T}:T{
+Use either \fB0.22.0\fR, \fB0.21.0\fR or \fB0.22.2\fR
+T}:T{
+Use \fB0.22.0\fR
+T}:T{
+\fBReturn Error\fR
+T}
+.TE
+.sp
+.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
 This command requires you to be authenticated with either the \fB\-\-token\fR option
 or using \fBcargo\-login\fR(1).

tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checklink

@@ -0,0 +1 @@
+checklink-target

tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checklink

@@ -0,0 +1 @@
+checklink-target