Confused about cargo version property


#1

Hi there,

It appears that Cargo requires a version = "0.0.1" property. Can someone explain to me what this does and why it is not wrong?

The way I see it, most of the time a piece of software is in development, and attaching a version descripter (other than the Git checksum or equivalent) makes no sense. If I’m working on a version 1.3.0 release, the current version is neither 1.3.0 nor 1.2.x, and in fact I likely won’t know which commit to call 1.3.0 until after the fact. So specifying a version number in a version-controlled file just seems wrong, doesn’t it?


#2

The version number only has significance for released software. In your development branch you may commit many backwards compatible as well as non-backwards compatible changes. So, it’s when you release a version that you bump the appropriate number.

It’s not a very good idea to depend on someone’s development branch as you don’t know in which state that code is in.

Version0.0.1 means patch 1 over previously released version 0.0.0, i.e. a released bug fix.


#3

It makes sense in the sense that if someone wants to depend on your library, they will want to have some reference for what version they are using. It first of all provides points of reference when talking between developers. Even if the library isn’t being released at all yet, it’s useful for people who use it anyways, to mark “more stable” versions, and to mark before major breaking changes.

The version marker comes in hand mainly when releasing on crates.io. You can release your library on crates.io, even if it isn’t stable or feature-complete at all. As long as your version is 0.*.*, “anything goes” for breaking changes. When releasing development versions on crates.io, the versions just mark stages of development. If you are about to make a bunch of breaking changes you can bump the version so that people have a semi-stable reference point.

Personally, I generally leave the version as 0.0.1-dev until the first release I make on crates.io. After that, I’ll just release versions on cargo as 0.1.0, 0.1.1, 0.1.2, etc. These version may have any kind of non-backwards-compatible changes, and I just release them so that someone depending on the in-development library can declare that version in their Cargo.toml for a snapshot of my library. The usage of -dev isn’t as far as I know, I just use it to tell the difference between a released version and something on the git tree.