Consider documenting why versions have been yanked

[shepmaster]

Background

What is your motivation?

I want to know if I need to be worried about continuing to use a yanked version of a crate or not

Feature request

Idea 1:

Create an issue that states that a version has been yanked, why it was yanked, then close the issue. I hope this wouldn't be much more overhead.

Idea 2:

Mark that a version was yanked and why in the appropriate CHANGELOG.

[vks]

I think usually we yank versions that broke semver.

[dhardy]

In this case, 0.7.1 was yanked because it depended on rand_core 0.5.0 while using features from 0.5.1, thus breaking for many users on upgrade (#890).

Regarding the general call to document why a version was yanked, you have a good point. We should add a policy to document yanking in the changelog where possible.

How effective would your proposed open/close issue idea be? I suppose anyone looking through issues should see this. I could also rename the title of the motivating issue (#890) and add an explanation there.

[dhardy]

Aha, I guess the reason our minimal-versions CI test did not pick up the issue with 0.7.1 is that it uses a path dependency to rand_core, thus always uses the version in the repo, not the published version. In contrast I believe Cargo does a build test before publishing, but does not use minimal versions.

[shepmaster]

How effective would your proposed open/close issue idea be?

I wouldn't follow such a process for my crates; the junk issues would annoy me. I merely provided it as a possibility. I started by searching the issue tracker and finding older things that mention yanking without ever explicitly saying a yank will/did happen.

I then skimmed the changelog, looking for the same information.

What method you use is totally up to you (or even if you do it at all!), I just wanted to bring along some suggestion instead of just providing a complaint.

[shepmaster]

Thanks!