Did you know about version numbers?

In our todays installment of my little „Did you know“-series we won't look at Clojure itself but an important infrastructure topic.

The Clojure ecosystem is growing steadily. New libraries spawn every day. This is a Good Thing™. Tools like maven, gradle, leiningen and ivy make life easier for the developer who intends to use these new libraries. However library developers should pay attention to some details.

Version Numbers

Every library should follow a sane release schedule. Otherwise other developers cannot really depend on it. This should be a fairly obvious fact. So one should come up with some versioning system.

While some people suggest to simply depend on certain changeset ids of the version control system, this can't really be useful. While some systems don't have file spanning changesets[1], there are also other problems. Eg. you can't use version ranges. How do you order SHA1 checksums? (No. The versioning system knows, but I don't want to install your system just to use your library.)

So something more involved is needed. But don't despair. This discussion is not new and smarter people than I am already put their energy into this! Please read, understand and use Semantic Versioning. It is easy (always good), already there (no need to roll your own) and supported by all the above mentioned tools (yeah). So it should be a no-brainer.

SNAPSHOT versions

Another important point concerning version numbers are so called SNAPSHOT versions. These snapshots have several subversions with the same official version tag. The idea is to provide updates of an development version without having the users of the library having to update the version tag every other day. You want to use snapshots if you take part in the development of a library.

However, if you use the library in production you probably won't want that the library changes every other day[2]. Maybe breaking things. Here you need „normal“ versions – not snapshots.

Upshot

All this is not new. But it seems to necessary to repeat it to bring it back on the radar. So please provide stable versions. With a sane versioning system. Understand snapshots. Don't provide them in the same repository[3] as stable versions.

Eventually, a version schedule will force you to plan your library. This will improve its quality in the end.

Footnotes

  1. Ok, ok. Maybe CVS isn't widespread anymore…
  2. There are exceptions to this rule. Maybe because you need an urgent bug fix not in a released version available. But that should be exactly that: an exception.
  3. If you do so and a user of the library uses a version range (as encouraged by semantic versioning), the next snapshot will override the last stable version.

Published by Meikel Brandmeyer on .