Fix docs for cargo publish --dry-run vs cargo package

[trevyn]

In latest nightly at least, cargo publish --dry-run and cargo package are not equivalent:

e@e egui-tetra2 % cargo publish --dry-run
    Updating crates.io index
error: crate [email protected] already exists on crates.io index
e@e egui-tetra2 % cargo package
   Packaging egui-tetra2 v0.5.1 (/Users/e/Documents/GitHub/egui-tetra2)
    Updating crates.io index
    Packaged 19 files, 135.3KiB (37.7KiB compressed)
   Verifying egui-tetra2 v0.5.1 (/Users/e/Documents/GitHub/egui-tetra2)
...

[rustbot]

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[weihanglo]

This sounds more like a regression from the development of -Zpackage-workspace. This starts happening since nightly-2024-09-17, which contains the cargo submodule update (rust-lang/rust#130377).

[weihanglo]

This is it: 6ede1e2 in #14448. The fix might need to consider the presence of --dry-run.

[weihanglo]

Changing the doc like this PR is also fine, if we consider they are not equivalent anymore.

@epage since you were involved in #14448, what do you think?

[epage]

This moved an error that happens after --dry-run stops to before. I view this as a positive improvement, helping to catch errors earlier.

As for the docs, it depends on what you mean by equivalent. @trevyn in the future, please start with an issue. This might seem like an obvious documentation bug but we need to dig more into your situation to really understand what should be updated, whether docs, something else, etc. In general, there are differences between cargo publish -n and cargo package and we added another (and --workspace has more). So the question is what you read from "equivalent" that you found this to be wrong and needed to be updated.

[trevyn]

Sure, i interpret "equivalent" to mean identical in function, which is not the case for the above example. (see https://doc.rust-lang.org/std/cmp/trait.Eq.html 😂)

My use case is to run publish --dry-run in CI, partly as an additional verification, but primarily to report the compressed package size.

I agree that publish --dry-run erroring here is an improvement, and happily switched to package, which works great for me.

I found the docs helpful to find this alternative, but in my mind and usage the two are indeed no longer "equivalent". :)

[epage]

This section of documentation is telling users how to prepare for publish by doing a one-off command,. In that context, cargo publish -n and cargo package are similar.

What command to run in CI to catch problems during development is a different situation that this documentation is not speaking to.

However, I'm not too sure the value of calling out cargo package here. imo that would be the reason would remove the reference.

[trevyn]

That was my initial reaction too, but this section of the docs was the first thing I found when my --dry-run failed and I was trying to figure out what to do about it, and package was indeed the solution.

Will defer to your judgement of course.

[trevyn]

"which is similar" instead of "which is equivalent"?

[weihanglo]

Sure, i interpret "equivalent" to mean identical in function,

Agree. They used to be “more equivalent” before -Zpackage-worksapce came out. I also agree that we should remove cargo package entirely from that sentence.

but this section of the docs was the first thing I found when my --dry-run failed and I was trying to figure out what to do about it, and package was indeed the solution.

An alternative to this is that we could expand the doc of cargo publish --dry-run a bit. We could document about it checks what cargo package does plus some extra stuff. If people don't want to talk to remote registries for those extra checks, use cargo package.