Versioning policy
=================

- Development follows ``git flow`` model. 
        * ``master`` branch keeps stable version.

        * ``develop`` branch merges the feature branch
          but keeps stable (unit-test compatible)

        * ``feature/`` (``f/``) branch is for daily development.

- After merging feature branch to develop,
  the package MUST be released as master branch (as a baseline) within 2 days,
  with versioning strategy as follows.

        * The version number for stable product (master)
          consists of 3 digits separated by dot, for example, ``3.14.2``.

                + The major number (``3``) only increments when
                  significant changes are applied.
                  It has happened only once,
                  when the python2 to python3 transition occurred.
                  I do not foresee to increment the major version
                  to ``4`` as of now (2014-07-20).

        * The medium number, ``14``, is incremented,
          if the changes include any changes of existing public user interface.
          For example,

                + Refactoring (for cases if any user interface is changed)

                + Removal of API

        * The minor number, ``2``, is incremented,
          if the changes do not include any changes of existing public API.
          For example,

                + Debug

                + Refactoring (without changes in user interface)

                + Addition of functionality

                + Addition of tests

                + Any update of document (new doc, new recipe)

        * ``a1``, ``a2``, ... can be added for develop trees,
          namely, ``3.14.3a2``.  If the change is extremely small,
          and not worthwhile to pay effort
          to release as minor release,
          you can just increment the alpha version number.

                + Changes that do not concern any functionalities,
                  for example, the typo fix of variables.

                + Minor update of document (typo fix, small clarification)

                + Minor update of error message (typo fix, small clarification)

        * ``.post1``, ``.post2``, ... can be added for post release (mainly for hotfix).
          For example, ``3.14.5.post1``.

History
-------

* Change the label of "pre" for pre-release version,
  but use "a" for alpha version.
  This will help to match Python or PIP custom.  See :pep:`440`.  On 2015-01-21.

* Clarification of using pre numbering on 2014-06-22, 2014-07-20.

* Baseline defined on 2014-05-19.