diff --git a/src/doc/man/cargo-yank.md b/src/doc/man/cargo-yank.md index 3b9185d6a65..2408187b1da 100644 --- a/src/doc/man/cargo-yank.md +++ b/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}}. diff --git a/src/doc/man/generated_txt/cargo-yank.txt b/src/doc/man/generated_txt/cargo-yank.txt index cd6bc2be4e6..47558ea0313 100644 --- a/src/doc/man/generated_txt/cargo-yank.txt +++ b/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 + , credentials, etc... 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. + + 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). diff --git a/src/doc/src/commands/cargo-yank.md b/src/doc/src/commands/cargo-yank.md index 8bf4f825c00..27229f3ebc0 100644 --- a/src/doc/src/commands/cargo-yank.md +++ b/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). diff --git a/src/etc/man/cargo-yank.1 b/src/etc/man/cargo-yank.1 index c144ea14f45..d143a16b43a 100644 --- a/src/etc/man/cargo-yank.1 +++ b/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 , credentials, etc... In the case of security +vulnerabilities, \fIRustSec\fR 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). diff --git a/tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checkisexec b/tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checkisexec new file mode 100755 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checklink b/tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checklink new file mode 120000 index 00000000000..326d735163a --- /dev/null +++ b/tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checklink @@ -0,0 +1 @@ +checklink-target \ No newline at end of file diff --git a/tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checklink-target b/tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checklink-target new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checknoexec b/tests/testsuite/init/mercurial_autodetect/in/.hg/wcache/checknoexec new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checkisexec b/tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checkisexec new file mode 100755 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checklink b/tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checklink new file mode 120000 index 00000000000..326d735163a --- /dev/null +++ b/tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checklink @@ -0,0 +1 @@ +checklink-target \ No newline at end of file diff --git a/tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checklink-target b/tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checklink-target new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checknoexec b/tests/testsuite/init/simple_hg_ignore_exists/in/.hg/wcache/checknoexec new file mode 100644 index 00000000000..e69de29bb2d