How to use "cargo yank"?

Question

I've published my crate and then realized that I've forgotten to include some small detail in my README.md. I've included that detail into README.md and did git commit and push. How to update my crate without having to change its version?

From the crates.io documentation:

cargo yank

Occasions may arise where you publish a version of a crate that actually ends up being broken for one reason or another (syntax error, forgot to include a file, etc.). For situations such as this, Cargo supports a yank of a version of a crate.

$ cargo yank --vers 1.0.1 

$ cargo yank --vers 1.0.1 --undo

I don't understand how to use it. Why 2 commands: one with another without --undo? Should I run them both? Or only one? Which?

Should I run crate package && crate publish after that? Or only cargo yank ...? Will that automatically update my crate?

Hungerford

Answer 1

You can't update your crate without publishing a new version. The crate repository is explicitly designed such that crates are immutable: once published, they never change, period.

Yanking is for when there is some serious problem with a published crate, such as a serious security vulnerability, or potential to damage user's data, or yes, because it just straight-up doesn't work. It's a signal that no one should be using that version of the crate for any reason. An incomplete README.md does not really meet that standard.

Just publish a new version, or hold off until you would be publishing a new version for some other reason.

---

As for why there are two commands: because one yanks a version, and the other un-yanks it. Un-yanking is not the same as publishing, it's just restoring the crate that was yanked as though it had never been yanked in the first place.

Rutty

It's a signal that -- what signal? – Hungerford

@Hungerford Yanking. – Rutty

I don't understand – Hungerford

@Jodimoro: That a version of a crate has been yanked is an indication to users that the version in question should not be used, because something is wrong with it. – Rutty

What indicator? Does crates install a special red-light led indicator to each user's computer and flash it when a crate is yanked? – Hungerford

@Jodimoro: Yanked crates show up as yanked in a crate's version history on crates.io. – Rutty