6.1 What's a Versioning Policy A versioning policy is merely a set of simple rules governing how version numbers are allocated. 6.2 Why is this one Rational? Because RubyGems provides support for version comparisons, we want to pick a policy that works well with the RubyGems comparisons and gives the end user what they expect. We call such a policy “rational”. Also, if we call non-working policies “irrational”, then we apply a little bit of social engineering to gently prod offenders to conform. 6.4 Ok, Give me the Details The RationalVersioningPolicy provides the following guidelines:
- Versions shall be represented by three non-negative integers, separated by periods (e.g. 3.1.4). The first integers is the ’’‘major’’’ version number, the second integer is the ’’‘minor’’’ version number, and the third integer is the ’’‘build’’’ number.
- A category 1 change (implementation detail) will increment the build number.
- A category 2 change (backwards compatible) will increment the minor version number and reset the build number.
- A category 3 change (incompatible) will increment the major build number and reset the minor and build numbers.
- Any ’’public’’ release of a gem should have a different version. Normally that means incrementing the build number. This means a developer can generate builds all day long for himself, but as soon as he/she makes a public release, the version must be updated.
# Versioning scheme: MAJOR.MINOR.PATCH # MAJOR bumps when API is broken backwards # MINOR bumps when the API is broken backwards in a very slight/subtle (but not fatal) way # -OR when a new release is made and propaganda is sent out. # PATCH is bumped for every API addition and/or bugfix (ideally for every commit) # Later DamageControl can bump PATCH automatically.
Interesting ideas for how to version "pre-releases" (release candidates)...
A version consists of an alternating series of release numbers and pre-release or post-release tags. A release number is a series of digits punctuated by dots, such as 2.4 or 0.5. Each series of digits is treated numerically, so releases 2.1 and 2.1.0 are different ways to spell the same release number, denoting the first subrelease of release 2. But 2.10 is the tenth subrelease of release 2, and so is a different and newer release from 2.1 or 2.1.0. Leading zeros within a series of digits are also ignored, so 2.01 is the same as 2.1, and different from 2.0.1. Following a release number, you can have either a pre-release or post-release tag. Pre-release tags make a version be considered older than the version they are appended to. So, revision 2.4 is newer than revision 2.4c1, which in turn is newer than 2.4b1 or 2.4a1. Postrelease tags make a version be considered newer than the version they are appended to. So, revisions like 2.4-1 and 2.4pl3 are newer than 2.4, but are older than 2.4.1 (which has a higher release number). A pre-release tag is a series of letters that are alphabetically before "final". Some examples of prerelease tags would include alpha, beta, a, c, dev, and so on. You do not have to place a dot before the prerelease tag if it's immediately after a number, but it's okay to do so if you prefer. Thus, 2.4c1 and 2.4.c1 both represent release candidate 1 of version 2.4, and are treated as identical by setuptools. ... Don't use - or any other character than . as a separator, unless you really want a post-release. Remember that 2.1-rc2 means you've already released 2.1, whereas 2.1rc2 and 2.1.c2 are candidates you're putting out before 2.1. If you accidentally distribute copies of a post-release that you meant to be a pre-release, the only safe fix is to bump your main release number (e.g. to 2.1.1) and re-release the project.