r/rust•
CrystalDev

Question: Managing Cargo/Crates.io versions in interaction with Git.

Hello everyone,

Since about 2 months I have been working on some projects. It made me wonder how people handle different Cargo/Crates.io versions in interaction with Git.

For example: Let's say I currently have a project version 1.0.0 and multiple people are working on it at the same time. Would they then all increment it to 1.0.1 on their specific branch / Pull Request? That would mean that if one PR would be merged others would automatically have to be updated with new numbers.

Or would a better approach be to use 1.0.0 for all Pull Requests and then do a different commit on master when the newly merged PR would together form 1.0.1? This however then would mean that the master branch (prior to 1.0.1 being released) would contain a more up to date version than crates.io.

I was wondering if would share your wisdom with me about this issue or if I am missing some key knowledge. If things could somehow be automated using for example Travis CI, that would be even better of course.

Posted Feb 6, 2019, 9:02 AM UTC

127
WellMakeItSomehow•

This however then would mean that the master branch (prior to 1.0.1 being released) would contain a more up to date version than crates.io.

Why would that be an issue?

5
Hobofan94leaf · collenchyma•

It's not a huge issue, and for some maintainers common practice to directly make a commit incrementing to the next version after publishing a release.

However it creates the problem that you can't patch a dependency in your Cargo.toml with a git dependency that e.g. has a bug fix that is not released yet by the maintainer, as cargo only allows patching with the same version number. There has been more than one occasion where I had to fork and decrement the version again to be able to patch a dependency.

5
CrystalDevOP•

I never thought about the idea to directly make a commit right after the release, thanks for that insight. It does however feel kind of ugly (in my opinion) to have separate commits just to represent that a certain version has been reached. I feel Git Tags should be used for those kind of things. But I guess its something we just need to deal with! I do really like Cargo and how easy it is to load other dependencies.

1
po8•

Make a dev branch. Make pull requests against the dev branch. When the dev branch is merged to master, update the version number and push to crates.io.

3
CrystalDevOP•

I think this is one of the best ways to deal with everything! Then you could even squash the commits when merging them into master and rename it as a certain version.

1
daborossfern•

The standard I see most crates is having the version as 1.0.0 throughout the development of 1.0.1, in PR branches and master branch, and after PRs have merged.

Then when all of the separate PRs have individually been merged, and tests pass for the merged result, the maintainer makes one more commit "Release 1.0.1" which simply changes version numbers wherever appropriate (Cargo.toml version, docs link urls, etc.). The release is very rarely, or never, done via a PR since it's the decision of the maintainer alone when to release, and no code is changed.

This is somewhat similar to your second situation, but it has the advantage of keeping a "working master" which already has PRs merged that are known to be good. This way more pull requests can be made against the master which already contains some features/fixes before the release: this is useful for avoiding merge conflicts, but also for splitting up big features into multiple PRs which can be reviewed separately, but depend on eachother.

I very rarely see rust projects use a dev branch or a -dev release tag, but those are also good alternatives if you're a huge project. For regular libraries this is overkill, but having a dev branch where all PRs are merged keeps the master at "release" all the time. It has the advantage of having a single branch which is always release-quality, but several disadvantages including:

  • crate could look unmaintained if a lot of work is done on dev branch before a big release, and it's been a long time since a commit on master
  • new developers need to realize this dev branch exists so they don't accidentally make their pull requests against master (which contains old code)
  • releasing things is more work (need to: merge dev into master, make release commit on master, do release, then merge master into dev)

The last strategy I know of is '-dev' version tags. This is essentially what I described first, but with the additional step of making a "Prepare for next development cycle" commit directly after the release commit which changes version from 1.0.1 to 1.0.2-dev. This means there's exactly 1 commit where version = 1.0.1, so that's an advantage for ambiguity reading history, and it makes sure people know that the master branch is dev-quality, not release-quality. I learned this first in java projects using maven, but it could be applied to Rust ones as well. It's main two disadvantages are:

  • no one in the rust community does this, so seeing a '-dev' tag will be slightly out of place
  • cargo and allows patching dependencies with git versions, but only if the version tag in the git branch matches the version released. -dev prevents this
  • more work when releasing versions (need to make an extra commit)
2
CrystalDevOP•

Thanks for your reply! I'll just stick to the first approach then :)

2