Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify Implications of Cargo Yank #11071

Closed
wants to merge 7 commits into from
Closed

Clarify Implications of Cargo Yank #11071

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9065c87
Update cargo-yank.md
tustvold Sep 10, 2022
17c711c
Review feedback
tustvold Sep 10, 2022
aa1f590
Tweak wording
tustvold Sep 10, 2022
e48b16f
Remove empty files
tustvold Sep 10, 2022
af6b722
Fix copypasta
tustvold Sep 10, 2022
d227ad6
Review feedback
tustvold Sep 27, 2022
1cba8b7
Fix typo
tustvold Sep 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
23 changes: 20 additions & 3 deletions src/doc/man/cargo-yank.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,26 @@ 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.
However, yanking a release will prevent cargo from selecting that version
when determining the version of a dependency to use. If there are no longer
any compatible versions that haven't been yanked, cargo will return an error.

The only exception to this is crates locked to a specific version by a lockfile,
these will still be able to download the yanked version to use it.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
However, yanking a release will prevent cargo from selecting that version
when determining the version of a dependency to use. If there are no longer
any compatible versions that haven't been yanked, cargo will return an error.
The only exception to this is crates locked to a specific version by a lockfile,
these will still be able to download the yanked version to use it.
Best practice is to yank a release *only* when it contains a serious flaw, such as
a security vulnerability, and when there is a newer semver compatible release
published. You do not need to yank a version to suggest users of your crate upgrade.
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 compatibile, 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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cargo will not use a yanked version for any new project

I think, that the concept of "new" requires clarification. When project is considered as "new"?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Practically speaking, I think "new" means any rust project that does not already have a Cargo.lock file.

I believe the basic guidance is that "libraries" (e.g. stuff published to crates.io that other applications can depend on) should not have a Cargo.lock: https://doc.rust-lang.org/cargo/faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

such as a security vulnerability

I think accidentally breaking semver compatibility might deserve mention there as well it can wreak havoc in downstream projects.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Best practice is to yank a release only when it contains a serious flaw, such as
a security vulnerability, and when there is a newer semver compatible release
published.

Even for security flaws: publish a new patch version and if you're really concerned, file a rustsec warning. No yanking required. The downstream user can then decide if they are even affected (e.g. for flaws that only affect certain platforms) and -- depending on how critical the flaw is -- update in a cadence that matches THEIR workflow. Remember: yanking a crate is a choice that the downstream user CANNOT make.

A good example that justifies yanking are license/copyright issues (e.g. you accidentally included code that cannot be used under the crate's license; or you've included personally identifiable information in some tests). Apart from that, I cannot think of a good reason to yank a crate. There's semver and patch releases provide a clear path forward and are THE tool the use in nearly every case.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably that explanation also should appear when you try to click "Yank" button on crates.io or run cargo yank

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated with a slightly tweaked version of this, PTAL


For example, consider a crate `bar` with published versions `0.22.0`, `0.22.1`,
tustvold marked this conversation as resolved.
Show resolved Hide resolved
`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 constraints,
tustvold marked this conversation as resolved.
Show resolved Hide resolved
following a given release being yanked

| Yanked Version / Semver Constraint | `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` |
weihanglo marked this conversation as resolved.
Show resolved Hide resolved
| `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
tustvold marked this conversation as resolved.
Show resolved Hide resolved

This command requires you to be authenticated with either the `--token` option
or using {{man "cargo-login" 1}}.
Expand Down
34 changes: 31 additions & 3 deletions src/doc/man/generated_txt/cargo-yank.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,37 @@ 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.
However, yanking a release will prevent cargo from selecting that
version when determining the version of a dependency to use. If there
are no longer any compatible versions that haven't been yanked, cargo
will return an error.

The only exception to this is crates locked to a specific version by a
lockfile, these will still be able to download the yanked version to use
it.

For 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 constraints, following a given release being yanked

+----------------------+-----------------------+-----------+----------+
| Yanked Version / | bar = "0.22.0" | bar = | bar = |
| Semver Constraint | | "=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).
Expand Down
23 changes: 20 additions & 3 deletions src/doc/src/commands/cargo-yank.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,26 @@ 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.
However, yanking a release will prevent cargo from selecting that version
when determining the version of a dependency to use. If there are no longer
any compatible versions that haven't been yanked, cargo will return an error.

The only exception to this is crates locked to a specific version by a lockfile,
these will still be able to download the yanked version to use it.

For 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 constraints,
following a given release being yanked

| Yanked Version / Semver Constraint | `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).
Expand Down
59 changes: 56 additions & 3 deletions src/etc/man/cargo-yank.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,62 @@ 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.
However, yanking a release will prevent cargo from selecting that version
when determining the version of a dependency to use. If there are no longer
any compatible versions that haven't been yanked, cargo will return an error.
.sp
The only exception to this is crates locked to a specific version by a lockfile,
these will still be able to download the yanked version to use it.
.sp
For 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 constraints,
following a given release being yanked

.TS
allbox tab(:);
lt lt lt lt.
T{
Yanked Version / Semver Constraint
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).
Expand Down