is using *Django Conntrackt*.

- Patch number is bumped when making purely bug-fix backwards compatible

  changes. Patch releases are generally more likely to remain stable simply due

  to limited scope of changes (new features can sometimes introduce unexpected

  bugs). It shouild be noted that due to relatively limited resources I have

  (plus, the roles are mainly used by myself :), patch releases might be a bit

  more scarce, and I might opt for going for minor release instead to reduce

  amount of work needed (backporting and releasing).

In addition to versioning schema, *Django Conntrackt* employs a specific

nomenclature for naming the branches:

- All new development and bug-fixing uses ``default`` branch as the base.

- Patch releases are based off the maintenance branches. Mainteance branches are

  named after the ``MAJOR`` and ``MINOR`` number of the version. For example, if

  a new release is made with version ``1.2.0``, the corresponding branch that is

  created for maintenance will be named ``1.2`` (notice the absence of ``.0`` at

  the end).

Writing release notes

---------------------

Release notes should be updated in relevant branches as the issues are

  VERSION

  -------

  GENERAL DESCRIPTION

  Breaking changes:

  New features/improvements:

  Bug-fixes:

Release issue template

----------------------

- Set *subject* to ``Release version MAJOR.MINOR.PATCH``.

- Set *description* to::

    Release version MAJOR.MINOR.PATCH. Release should be done

    according to release procedures outlined in offline documentation.

Backporting fixes

-----------------

When a bug is discovered in one of the roles (or maybe documentation), and it

should be applied to maintenance branch as well, procedure is as follows:

1. Create a new bug report in `issue tracker

   <https://projects.majic.rs/conntrackt>`_. Target version should be

   either the next minor or next major release (i.e. whatver will get released

2. Create a copy of the bug report, modifying the issue title to include phrase

   ``(backport to MAJOR.MINOR)`` at the end, with ``MAJOR`` and ``MINOR``

   replaced with correct versioning information for the maintenance

   branch. Make sure to set correct target version (patch release).

3. Resolve the bug for next major/minor release.

4. Reslove the bug in maintenace branch by backporting (using graft if

   possible) the fix into maintenace branch. Make sure to reword the

   commit message (to reference the backport issue) .

Releasing new version

---------------------

The following procedure is applicable to both major/minor and patch

releases, with any relevant differences pointed out in the individual

steps.

Perform the following steps in order to release a new version:

1. Verify that there are no outstanding issues blocking the release.

2. Prepare release environment:

   1. Switch to the project Python virtual environment::

        workon conntrackt

   2. Set release version, and set issue associated with making the

      release::

        ISSUE="CONNT-NUMBER"

   3. Verify the information has been set correctly::

3. If this is a new major/minor release, prepare the maintenance

   branch:

   .. warning::

      Make sure **not** to run these steps when making a patch release!

   1. Create the maintenance branch::

        hg branch "$BRANCH"

   2. Update versioning information in documentation and setup

      script::

        sed -i -e "s/^version = .*/version = '${BRANCH}-maint'/" docs/conf.py

        sed -i -e "s/^    version=.*/    version='${BRANCH}-maint',/" setup.py

        sed -i -e "s/^dev$/${BRANCH}-maint/" docs/releasenotes.rst

   3. Fix the title underline for version string in

      ``docs/releasenotes.rst``.

   4. Show differences before committing::

        hg diff

        python setup.py sdist

   4. Test the quick-start instructions to ensure they are still

      applicable. When installing the package, make sure to use the

      source distribution package from previous step.

   5. Correct any outstanding issues prior to proceeding further, and

      repeat the test cycle for any sort of change, ammending the

      previous commit if possible (instead of creating new ones).

7. Push release to PyPI:

   1. Tag the release::

        hg tag "$VERSION"

   2. Push the (tested) built source distribution::

        python setup.py upload

8. Clean-up the maintenance branch:

   1. Start a new release notes section in ``docs/releasenotes.rst``::

   2. Update versioning information in documentation and setup

      script::

        sed -i -e "s/^version = .*/version = '${BRANCH}-maint'/" docs/conf.py

   3. Fix the title underline for version string in

      ``docs/releasenotes.rst``.

   4. Show differences before committing::

        hg diff

   5. Commit the changes::

        hg commit -m "$ISSUE: Bumping version back maintenance."

9. Clean-up the default branch if you have just released a new

   major/minor version:

   .. warning::

      Make sure **not** to run these steps when making a patch release!

   1. Switch to default development branch::

        hg update default

   2. Verify the switch::

        hg branch

   3. Update versioning information in release notes::

   4. Start a new release notes section in ``docs/releasenotes.rst``::

   5. Fix the title underlines for version strings in

      ``docs/releasenotes.rst``.

   6. Show differences before committing::

        hg diff

   7. Commit the changes::

        hg commit -m "$ISSUE: Starting new release notes in default development branch."

10. Wrap-up changes on external services:

    1. Push the changes to upstream repository and its mirror::

         hg push

         hg push bitbucket

    2. Go to `Read the Docs administrative pages

       <https://readthedocs.org/projects/django-conntrackt/>`_, and

       add the build for new version, retiring any unsupported

       versions along the way.