Versioning and Compatibility

This document outlines versioning of the Cement framework, and extensions that are included with the official source.


This outline uses fictitious version numbers to avoid confusion between actual releases and this doc. Cement is versioned as follows, using the version 0.2.4 as the example:

  • 0 = Code Base
  • 2 = Major Release Version
  • 4 = Minor Release Version

That said, the Major Release Version and the Minor Release Version both honor the following scheme:

  • Even = Stable
  • Odd = Development

Therefore, if 0.2.4 (even, even) is the current stable release of the ‘0’ branch, then 0.2.5 (even, odd) is the ‘in progress’ version in the Git ‘master’ branch. Once 0.2.5 reaches releasability it would be released as 0.4.6 stable (even, even).

Development versions also follow the same scheme. The next major release that breaks API compatibility would be versioned as 0.3.1 (odd, odd). Once a ‘stable enough’ version of the development branch reaches releasability, it will be released as 0.3.2 (odd, even) meaning the branch is development, but it is a semi-stable release.

Any time API compatibility changes we will up the Major Release Version. We handle this in of Cement applications by doing something like:

    "cement2 >=0.2.4, <0.3"

This means, if you write an application on top of cement == 0.2.4 then your application should be compatible with all versions of 0.2.x, however may experience incompatibilities with versions >=0.3 because 0.3 is the next development version where API compatibility changes. For that reason the next major development branch is 0.3 (odd) currently, and the next major stable branch of cement will be 0.4 (even). Both 0.3 (development) and 0.4 (stable) break compatibility with previous versions of Cement < 0.3.

The ‘Code Base’ version more or less designates a ‘full rewrite’. Meaning that within the same code base (i.e. ‘0’) even in the next major version that break compatibility, you should be able to make your application work with only a few changes. Where as, in the next code base (i.e. 1) it is likely that you will need to make significant changes, or possibly rewrite your application to work on the newer code base.

To keep API compatible, and non compatible development separate we work out of two Git repos.

  • master: development that is API compatible with current stable.
  • portland: development that is API incompatible with current stable.

Python Compatibility

The Cement2 Core library is compatible with Python 2.6+ and Python 3+. Some extensions may not be Python 3 compatible and would therefore be packaged separately (though still part of the official source).

Project Versions

Table Of Contents

Previous topic


Next topic


This Page