diff --git a/src/doc/man/cargo-yank.md b/src/doc/man/cargo-yank.md index 8ad28ef243f..946e98c8511 100644 --- a/src/doc/man/cargo-yank.md +++ b/src/doc/man/cargo-yank.md @@ -15,9 +15,9 @@ 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}}. @@ -25,6 +25,56 @@ 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 . + +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 diff --git a/src/doc/man/generated_txt/cargo-yank.txt b/src/doc/man/generated_txt/cargo-yank.txt index e07e52626fe..dee3583a504 100644 --- a/src/doc/man/generated_txt/cargo-yank.txt +++ b/src/doc/man/generated_txt/cargo-yank.txt @@ -13,9 +13,9 @@ 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). @@ -23,6 +23,62 @@ DESCRIPTION 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 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 + . + + 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 diff --git a/src/doc/src/commands/cargo-yank.md b/src/doc/src/commands/cargo-yank.md index b1371185e02..7e020235c1a 100644 --- a/src/doc/src/commands/cargo-yank.md +++ b/src/doc/src/commands/cargo-yank.md @@ -15,9 +15,9 @@ 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). @@ -25,6 +25,56 @@ 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 . + +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 diff --git a/src/etc/man/cargo-yank.1 b/src/etc/man/cargo-yank.1 index 71de0ae37db..c58ee28e51f 100644 --- a/src/etc/man/cargo-yank.1 +++ b/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 +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 and contact +them at \&. +.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