Clarify Implications of Cargo Yank

[tustvold]

What does this PR try to resolve?

I found the documentation for cargo yank was not especially clear on the implications of yanking a crate, and I have seen this causing confusion within the community - tafia/quick-xml#475.

On a somewhat related note, I have been observing lots more crates getting yanked recently and this is resulting in a fair amount of dependency upgrade busywork. I think/hope part of this is a documentation issue.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) soon.

Please see the contribution instructions for more information.

[Mingun]

I think it would be useful to add an example here

[adamreichold]

If the implications are discussed, I think mentioning the usual course of action (publishing a semver-compatible release before yanking) would be nice as well.

[weihanglo]

The first sentence is too long for me to get it at the first glimpse. Is it possible to make it simpler?

Besides, I believe we should follow the step here to generate docs.

[alamb]

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

[Mingun]

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"?

[alamb]

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

[adamreichold]

such as a security vulnerability

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

[crepererum]

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.

[Mingun]

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

[tustvold]

Updated with a slightly tweaked version of this, PTAL

[weihanglo]

Thank you for posting this. Looks nice to me so far!

[ehuss]

r? @weihanglo

[weihanglo]

How do you feel putting them in the end of this DESCRIPTION section, under a subsection heading like ### When to yank or something better?

Just trying to make it look less lengthy and more organized. The content itself is really well-written! Thank you!

[weihanglo]

This paragraph concludes the example really well, thought it feels like somewhat a duplicate of line 49-50. A challenge in documentation is putting the right amount. Could we find a way to merge them and make it more concise? It is not a blocker on merging this PR though.

[weihanglo]

Friendly ping @tustvold. Just checking in to see if you are still interested in working on this, or if you had any questions. Thank you :)

[weihanglo]

This PR is indeed valuable, and I want it to move forward!!
I posted a PR #11862 with only moving paragraphs around. Thanks everyone for participating the discussion and mostly @tustvold for writing all these down. Close in favor of #11862.