setup.py: versions

Date: January 23rd 2016
Last updated: January 24th 2016

Todays entry looks at setting versions with setuptools.

The most important part about this is to ensure that setuptools and easy_install can tell which package is most recent. A version number is a series of numbers and letters that are treated numerically (e.g. 1.0, 2.0.1... 3.3.3).

Convention: major.minor[.patch][sub]

# milestones

major = major milestones  
minor = features added  
patch = bug fixing  
sub = incremental releases

    sub alpha  [functionality changes = a1, a2, a3... aN]
    sub beta  [bug fixes = b1, b2, b3... bN]
    sub final pre-release [testing = pr1, pr2, pr3... prN]

Quick start

Initial release = 0.1.0  
Added features = 0.2.0 
Bug fix patch = 0.2.1
first alpha release = 0.2.1a1   
second alpha release = 0.2.1a2   
sub release bug fix = 0.2.1b1  
final test version of patch  = 0.2.1pre1
Several commited bug fixes = 0.2.2
Final set of features added = 1.0.0

Tip:

Add CHANGES.txt file to the root directory of your distribution.

# version, date, notes
v0.1.0, 20150123, Initial release
v0.1.1, 20150123, Minor updates

Some things to note:

Pre-release

  • 01.2 is the same as 1.2 (leading zero ignored)
  • 1.2 is the same release number as 1.2.0
  • 1.10 is the tenth sub-release of version 1 and not the same as 1.1
  • a pre-release tag looks like 1.2c1 (candidate 1)
  • 1.2c1 (release candidate 1) is older than 1.2

  • But, 1.2c1 is newer than 1.2b1 and 1.2a1

  • a pre-release tag is just a series of letters that alphabetically come before the "final"

    • alpha => 1.2 alpha1 (spaces after numbers ok)
    • beta => 1.2beta1
    • dev => 1.2-dev1

  • There are three special pre-release tags

    • pre
    • preview
    • rc
    • 1.2pre1 == 1.2preview1 == 1.2rc1 == 1.2c1

post-release

  • a post-release tag is a series of letters alphabetically equal to or higher than "final or a dash"
  • a post-release tag looks like 1.2pl or 1.2-l
  • a post-release tag (1.2pl) is older than the next sub-release (1.3)
  • a post-release tag is usually appended with a patch number or a datestamp (e.g. 1.2-r1234 or 1.2-20160123)

long release names

  • 1.2a4.dev-r1234
    • fourth alpha release of 1.2
    • This is a pre-release (due to the dev tag)
    • This version is considered older than 1.2 and 1.2a4
    • and is an in development version of the fourth alpha release
    • revision number 1234

verify release names

from pkg_resources import parse_version
parse_version('1.2a4.dev-r1234') < parse_version('1.2.0')
parse_version('1.2a4.dev-r1234') < parse_version('1.2.1')

results matching ""

    No results matching ""