Versions

tinio edited this page Aug 22, 2011 · 3 revisions
Clone this wiki locally

The main Armstrong project uses a versioning scheme similar to the Ubuntu project. Major releases are given a version number of the year and month it was released. For example, our June 2011 release is 11.06, our September release is 11.09, and so on.

Release dependencies

Each major release has a series of dependencies. The dependencies are tagged to a specific minor version of the packages that are included. That is to say, if version 1.0 of the armstrong.apps.articles application is included in a full release, the actual dependency inside setup.py is declared as:

'armstrong.apps.articles>=1.0.0,<=1.1'

Keeping with the pattern of Django development as of version 1.3, only security bugfixes are back ported to bugfix releases, so this range of version dependencies can be made with no worry of behavior changing.

Versioning of components

Armstrong is broken into many components, each installable independently of the entire system. These systems are versioned separately of the main Armstrong version and follow the SemVer, or Semantic Versioning style of version numbering. That is:

<major>.<minor>.<bugfix>

As long as the <major> version is at 0, the package is considered non-production. As soon as the package is being used or is ready to be used as production software, it is promoted to a major version of 1. The first production release of each package is 1.0.0.

In addition to the main versions of a release, we have also adopted the use of alpha, beta, and rc plus an additional number to signify releases that are in various states of readiness. This is to allow releases according to distribute's version number parsing.

Packages that currently have development happening in them should be one minor release number higher than their current stable release, with a bugfix version of 0, followed by alpha.0. alpha.0 releases are only used to signify development releases. Actual alpha releases start at alpha.1. For example, while in initial development, armstrong.cli has a version of 0.1.0.alpha.0. It's first unstable release will be 0.1.0, at which point the setup.py in the repo should be bumped to version 0.2.0.alpha.0.

Backwards Incompatible Changes and Public APIs

Once a component reaches a 1.0.0 stable release, the public API is considered defined and will not break compatibility during the duration of all future 1.x.x releases. Any break in the public API results in the major version being advanced one number.

The public API is considered to be documented methods. Internal methods that are not documented are not subject to as strict of an interpretation, though every effort will be made to keep all internal APIs consistent as well.

Public APIs can generally be thought of as models, managers, model fields and mixins, forms, the admin interface, management commands, and any tasks that accompany a component unless explicitly marked in documentation as an internal API. Backwards compatibility does not preclude the addition of behavior, but does mean that all behavior that is present as of 1.0.0 will remain available as-is throughout.