Skip to content

Instantly share code, notes, and snippets.

@Rufflewind
Last active July 3, 2016 03:33
Show Gist options
  • Save Rufflewind/03f4e03f7cfa52b8f07d to your computer and use it in GitHub Desktop.
Save Rufflewind/03f4e03f7cfa52b8f07d to your computer and use it in GitHub Desktop.
Versioning policy

Versioning policy

Some of my projects have 3-component version numbers. Others have 4-component version numbers. Be aware that the meaning of these two kinds of version numbers differ.

3-component version numbers

0.0.0
| | |
| | +-- backward compatible changes (bug fixes)
| +---- backward compatible changes (new features)
+------ backward incompatible changes

This is consistent with the usual Semantic Versioning conventions. I use these in majority of my projects, including some Haskell ones.

4-component version numbers (Haskell-specific)

For some (but not all) Haskell projects, I use 4-component version numbers as recommended by the Haskell package versioning policy (PVP).

One thing that irks me is that it leaves the meaning of the upper two components unspecified. (There are also a few things that I don't quite agree with too.) So here's an attempt to clarify the versioning policy that are used in my projects:

0.0.0.0
| | | |
| | | +-- backward compatible changes (bug fixes)
| | +---- backward compatible changes (new features)
| +------ backward incompatible changes to Experimental modules
+-------- backward incompatible changes to Stable modules

In other words, if you only use Stable features then you are free to ignore all but the first number, which is expected to occur rarely.

Compatibility is defined in the same manner as in the official PVP but with one difference:

  • Deprecation is considered to be a compatible change (-Werror is a really big hammer: fine for testing during development, but probably a bad idea in production).

Compatibility diagram

Legend:

  • *** "does not work"
  • --- "unknown"
  • === "known to work"

Example:

*** 1.1 === 1.2 ---

This means:

  • does not work on versions below 1.1
  • known to work on versions between 1.1 and 1.2
  • no information on versions above 1.2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment