PSA: please "git tag" your crates.io releases

Time and again, I come across crates where I’d like to check what changes are already released, and where it’s near impossible to find out which exact git commits the releases are based on. The only way is to check the timestamps, but even that’s kind of hard since commits in the PR queue can be much older than the point they are merged at.

Sometimes there is some dedicated release commit (“bump version to x.y”) which helps, but it’s not needed if you just tag after cargo publish succeeds. It’s really quite easy and helps tremendously.

It’s also very useful for verification purposes (“did that crates.io source really come from that repository”).

18 Likes

i think we can and should warn on Cargo publish, if the commit is not tagged, the same way we warn if there are uncommitted changes. Could you open an issue on the Cargo repo perhaps?

13 Likes

For example Cargo release makes the tag after “cargo publish”. I think this is a good practice, since I don’t want to make a tag for a publish that failed. (But that can be handled, just need to remember to delete any failed publish’s tag before pushing.)

Using such a release wrapper is a good idea - it makes the git tagging a part of the publishing step. With many crates, I wouldn’t have bothered with tags if it wasn’t part of an integrated process. (I’ve since noticed how useful tags are for release management and checking what changed since a specific release).

3 Likes

Interesting point! I think that making it built-in to Cargo is a significant thing: I expect that people who regularly forget to tag things(like me) are those who don’t use cargo release for no real reason.

I can imagine that we can add something like

cargo release —tag

That way, we can have “tag after release”, and we get automatic naming of the tags.

A warning looks like a simpler feature at the first sight, and —tag could serve like a way to fix the warning easily.

Not everyone uses git though :frowning: Perhaps this could be a cargo plugin instead?

Another trick I use is doing git log or git blame on Cargo.toml.

1 Like

Good point! Afaik there are two VCS supported right now for cargo, HG and git, right?

How about checking if the project is under source control and emit a warning conditionally? (I don’t know how HG works, but I guess they also have tags)

It’s true, but I think absolute majority does use git, and we already have git-specific logic there:

It would be much less useful as a plugin: cargo release already exist, and most people just don’t use it. Plugins are useful for stuff you know you need, but for stuff you don’t know you need, I fear we need built-in warnings, if the cost/benefit ratio is reasonable.

Aside: why do we special-case git here? The technical reason is that we already ship libgit2 as part of Cargo to interact with index, so the implementation is easy. For mercurial, pijul, etc we’ll need either to call to external binary (which adds a host of new error conditions) or ship libgit2-analogs with Rust (which is a rather large dep for a relatively small feature). The non technical reason is probably that git, at the moment, is indeed the most popular vcs for Rust crates.

I’m advocating for Cargo to automatically add equivalent of git-rev = $(git rev-parse HEAD) to the rewritten Cargo.toml in the package. This would allow crates.io/crates.rs to link versions to git.

3 Likes

I agree, and I’ll (try to remember to) try out cargo release next time I have an opportunity.

I’ve used that too, but unfortunately some tend to bump the version in Cargo.toml directly before a release, while others do it directly after :frowning:

This would already be a step up! Am I remembering correctly that cargo already warns about uncommitted changes on publish? (There’s of course no guarantee that the commit exists in the repo, but there’s always ways to screw up if you want to.)

As far as alternate VCS go, there’s already an extensive selection implemented for cargo new; this handling should have alternatives as well.

according to cargo help init, i can specify the following for --vcs:

[possible values: git, hg, pijul, fossil, none]

Maybe this has to do with which VCS software is installed on the machine though?

I’ve wanted cargo publish to add a git tag for a long time; I have a three digit issue open for it as a feature request, with a possible design.

3 Likes
2 Likes

Added some mentoring instructions: https://github.com/rust-lang/cargo/issues/841#issuecomment-438322649

I think this would’t be too hard to implement, so if someone from Cargo team adds E-mentor label, we might get this fixed soon.

Semi-related, i read this post (Ctrl+F GitHub for the relevant part) a while ago, where the author points out that on npm it’s possible to publish a package without the source ever showing up in any public git. Does that problem exist as well with cargo/crates.io? Is there any web interface where i can browse the source+history of the published crate versions?

Of course it is. And that's not a "problem" so much as giving crate authors the freedom to not use git, or any VCS at that.

The matter of this thread is that if you're already using a public repository, it should be common courtesy to tag the releases there.

1 Like

But the source of crates hosted on crates.io is public anyway (it ends up in our local cargo caches when we use the crates), and doing diffs between releases does not require a VCS.

It’s since recently sneaking in this info on publish, https://github.com/rust-lang/cargo/pull/5886 seems to be under the radar for now.

Nice to know. The reason why I only came up with hg is the configuration doc for cargo https://doc.rust-lang.org/cargo/reference/config.html

# By default cargo new will initialize a new Git repository. This key can be
# set to hg to create a Mercurial repository, or none to disable this
# behavior.
vcs = "none"

Is this just outdated or just an example (then I would like to see “This key can be set to hg for example…”

Seems to be outdated: