-
Notifications
You must be signed in to change notification settings - Fork 2.4k
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.
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
doc: clarify implications of cargo-yank
#11862
Conversation
src/doc/man/cargo-yank.md
Outdated
license/copyright issues, accidental inclusion of | ||
[PII](https://en.wikipedia.org/wiki/Personal_data), credentials, etc... |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I might caution against this recommendation. Copyright, PII, and credential leakage should email [email protected] (or whichever registry you published to) to permanently delete the affected versions.
Other examples of when to yank might be:
- An accidental publish.
- An unintentional semver breakage.
- Egregious breakage (marginally unusable).
(I imagine it would be good to brainstorm other examples to recommend.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice catch. Updated.
Copyright, PII, and credential leakage should email [email protected] (or whichever registry you published to) to permanently delete the affected versions.
Do you think it should also mention this? I feel it is a bit much.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it would be good to mention. I think it helps provide more information on what actions someone should take in those situations (instead of leaving them to guess if they should use yank
or not). Another thought is to also maybe point them at https://crates.io/policies?
I'd also maybe consider removing "credential leakage", and instead say that if you have leaked credentials, the recommended process is to revoke those credentials. Once it is published, it is too late to assume they haven't been copied. I'm not even sure if crates.io will remove a crate in that circumstance (their removal criteria is fairly limited).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated. Let me know if it is too much :)
src/doc/man/cargo-yank.md
Outdated
|
||
This command requires you to be authenticated with either the `--token` option | ||
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 `0.22.0` and another crate `bar` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just a minor note. I'm not sure if you picked 0.x versions for these examples on purpose, but I generally try to avoid them since people can be confused or can normalize their behavior. (It's not too important, just something I want to caution about.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree with you on that. Changed them to 1.5.x
(just a random pick).
@bors try |
doc: clarify implications of `cargo-yank` ### 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.
I think this is ready for another round of review :) |
@Muscraft Just checking if you'll have a chance to review this. It looks good to me, but I think it is good to have new perspectives on the documentation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me, Thanks!
@bors r |
☀️ Test successful - checks-actions |
Update cargo 10 commits in ac84010322a31f4a581dafe26258aa4ac8dea9cd..569b648b5831ae8a515e90c80843a5287c3304ef 2023-05-02 13:41:16 0000 to 2023-05-05 15:49:44 0000 - xtask-unpublished: output a markdown table (rust-lang/cargo#12085) - fix: hack around `libsysroot` instead of `libtest` (rust-lang/cargo#12088) - Optimize usage under rustup. (rust-lang/cargo#11917) - Update lock to normalize `home` dep (rust-lang/cargo#12084) - fix: doc-test failures (rust-lang/cargo#12055) - feat(cargo-metadata): add `workspace_default_members` (rust-lang/cargo#11978) - doc: clarify implications of `cargo-yank` (rust-lang/cargo#11862) - chore: Use `[workspace.dependencies]` (rust-lang/cargo#12057) - support for shallow clones and fetches with `gitoxide` (rust-lang/cargo#11840) - Build by PackageIdSpec, not name, to avoid ambiguity (rust-lang/cargo#12015) r? `@ghost`
A continuation of #11071. Below are copied from there.
r? @Muscraft if you have time to review
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.