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

birkenfeld · November 13, 2018, 6:52am

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").

matklad · November 13, 2018, 7:42am

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?

bluss · November 13, 2018, 10:17am

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).

matklad · November 13, 2018, 12:22pm

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.

carols10cents · November 13, 2018, 12:48pm

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

carols10cents · November 13, 2018, 12:49pm

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

hellow · November 13, 2018, 1:11pm

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)

matklad · November 13, 2018, 1:35pm

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

github.com

rust-lang/cargo/blob/541e990681bc0c059a5fe8b32f60d87d00875de0/src/cargo/ops/cargo_package.rs#L174


      
                      )
                  }
              }
              Ok(())
          }
          
          
// Check if the package source is in a *git* DVCS repository. If *git*, and
          // the source is *dirty* (e.g. has uncommited changes) and not `allow_dirty`
          // then `bail!` with an informative message. Otherwise return the sha1 hash of
          // the current *HEAD* commit, or `None` if *dirty*.
          fn check_repo_state(
              p: &Package,
              src_files: &[PathBuf],
              config: &Config,
              allow_dirty: bool
          ) -> CargoResult<Option<String>> {
              if let Ok(repo) = git2::Repository::discover(p.root()) {
                  if let Some(workdir) = repo.workdir() {
                      debug!("found a git repo at {:?}", workdir);
                      let path = p.manifest_path();
                      let path = path.strip_prefix(workdir).unwrap_or(path);

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.

kornel · November 13, 2018, 1:46pm

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.

birkenfeld · November 13, 2018, 2:26pm

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

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.

mmmmib · November 13, 2018, 3:27pm

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?

steveklabnik · November 13, 2018, 3:41pm

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.

mmmmib · November 13, 2018, 3:44pm

https://github.com/rust-lang/cargo/issues/841

matklad · November 13, 2018, 4:10pm

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.

mmmmib · November 13, 2018, 5:22pm

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?

birkenfeld · November 13, 2018, 5:32pm

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.

mmmmib · November 13, 2018, 5:44pm

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.

bluss · November 13, 2018, 6:56pm

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.

hellow · November 14, 2018, 7:33am

Nice to know. The reason why I only came up with hg is the configuration doc for cargo Configuration - The Cargo Book

# 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..."

mmmmib · November 14, 2018, 12:44pm

Seems to be outdated:

github.com

rust-lang/cargo/blob/bd32ba721fcee9b8d284552982789e0f2bf06c8d/src/cargo/ops/cargo_new.rs#L18


      
          use git2::Repository as GitRepository;
          
          use core::{compiler, Workspace};
          use util::{internal, FossilRepo, GitRepo, HgRepo, PijulRepo, existing_vcs_repo};
          use util::{paths, Config};
          use util::errors::{CargoResult, CargoResultExt};
          
          use toml;
          
          #[derive(Clone, Copy, Debug, PartialEq)]
          pub enum VersionControl {
              Git,
              Hg,
              Pijul,
              Fossil,
              NoVcs,
          }
          
          #[derive(Debug)]
          pub struct NewOptions {
              pub version_control: Option<VersionControl>,

Topic		Replies	Views
Lib.rs version pages now link to git commits announcements	13	729	September 26, 2022
A tool I recommend: cargo-release	1	602	January 12, 2023
Does anyone use Github Actions to run cargo publish?	5	1572	September 9, 2023
Error: 2 files in the working directory contain changes that were not yet committed into git help	12	1091	October 29, 2020
Changelog for new crate versions	4	744	January 12, 2023

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

Related Topics