releaseprocedures

Release procedures

==================

This section documents various release procedures. This includes:

- General versioning schema principles.

- General backporting principles.

- Releases of major versions.

- Releases of minor versions.

- Releases of patch versions.

Versioning schema

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

*Majic Ansible Roles* project employs `semantic versioning

<http://semver.org/>`_ schema. In short:

- Each version is composed of major, minor, and patch number. For example, in

  version ``1.2.3``, ``1`` is the major, ``2`` is the minor, and ``3`` is the

  patch number.

- Major number is bumped when making a backwards incompatible

  change. I.e. anything that depends on *Majic Ansible Roles* may need to make

  changes in order to keep working correctly.

- Minor number is bumped when new features or changes are made without breaking

  backwards compatibility. I.e. if you were you using vrersion ``1.2.3``, you

  should be safe to upgrade to version ``1.3.0`` without making any changes to

  whatever is using *Majic Ansible Roles*.

- 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 used for release, *Majic Ansible Roles* employs

a specific nomenclature for naming the branches:

- All new development and bug-fixing first happens on the master branch.

- An implementation branch has its name set to the associated issue,

  lower-cased. For example, if the issuer number is ``MAR-43``, the

  implementation branch will be named ``mar-43``. Normally these branches are

  only local, but if necessary they can be pushed to the repository.

- 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).

Backporting fixes

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

From time to time it might become useful to apply a bug-fix to both the master

branch, and to maintenace branch.

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/majic-ansible-roles>`_. Target version should be

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

   from the master branch).

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.

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

4. Reslove the bug in maintenace branch by backporting (cherry-picking if

   possible) the fix into maintenace branch. Make sure to resign the commit

   since cherry-picking invalidates signature.

Releasing new minor/major version

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

New minor/major releases are based off of the current master branch ``HEAD``.

When releasing a new minor/major version, procedure is as follows:

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

2. Switch to the project Python virtual environment::

     workon majic-ansible-roles

3. Make sure you are on the ``master`` branch::

     git checkout master

4. Extract current version, set release version, and set issue associated with

   making the release::

     CURRENT_VERSION=$(grep '^version = ' docs/conf.py | sed -e "s/^version = '//;s/'$//")

     NEW_VERSION="MAJOR.MINOR.PATCH"

     ISSUE="MAR-NUMBER"

5. Double-check what the associated issues is, what the current version string

   is, and what the release version will be::

     echo "[$ISSUE] $CURRENT_VERSION -> $NEW_VERSION"

6. Create issue branch::

     git checkout -b "${ISSUE,,}"

7. Verify that documentation builds and looks correct::

     (cd docs/; make clean html; firefox _build/html/index.html)

8. Test deployment of test site from scratch to make sure all roles behave

   correctly.

9. Add release notes to file ``docs/releasenotes.rst``. Release notes template

   should be as follows::

     GENERAL DESCRIPTION

     New roles:

     * ``ROLE``, DESCRIPTION.

     Breaking changes:

     * ``ROLE`` role

        * CHANGE DESCRIPTION

     New features/improvements:

     * ``ROLE`` role

       * FEATURE/IMPROVEMENT DESCRIPTION

     Bug-fixes:

     * ``ROLE`` role

       * BUG-FIX DESCRIPTION

10. Clean-up the documentation build, and check what files need to be updated::

      (cd docs; make clean; grep -r "${CURRENT_VERSION/./\\.}" .)

11. Update all relevant documents with new version information, as obtained from

    the previous command. At the very least this includes changes to:

    - ``docs/conf.py``

    - ``usage.rst``

12. Ensure documentation builds correctly::

      (cd docs/; make clean html)

13. Show the changes before making a commit::

      git diff docs/

14. Commit the changes::

      git add docs/

      git commits -m "$ISSUE: Preparing for release $NEW_VERSION."

15. Create annotated and signed Git tag::

      git tag --sign -a "$NEW_VERSION" -m "RELEASE DESCRIPTION"

16. Clean-up the documentation build, check what files need to be switched back

    to development version, and determine development version::

     (cd docs; make clean; grep -r "${NEW_VERSION/./\\.}" .)

     echo "${NEW_VERSION%.*}-dev"

17. Update all relevant documents with development version information, as

    obtained from the previous command. At the very least this includes changes

    to:

    - ``docs/conf.py``

    - ``usage.rst``

18. Show the changes before committing them::

      git diff docs/

19. Commit the changes::

      git add docs/

      git commits -m "$ISSUE: Bumping version to ${NEW_VERSION%.*}-dev (switching back to development)."

20. Verify GnuPG signatures::

      git gpgcheck

      git verify-tag "$NEW_VERSION"

21. Merge changes back into the master branch::

      git checkout master

      git merge "${ISSUE,,}"

22. Push the tag and changes to master::

      git push

      git push origin "${NEW_VERSION}"

23. Create the maintenace branch::

      git checkout -b "${NEW_VERSION%.*}" "$NEW_VERSION"

24. Clean-up the documentation build, check what files need to be switched to

    maintenace version, and determine maintenace version::

      (cd docs; make clean; grep -r "${NEW_VERSION/./\\.}" .)

      echo "${NEW_VERSION%.*}-maint"

25. Update all relevant documents with new version information, as obtained from

    the previous command. At the very least this includes changes to:

    - ``docs/conf.py``

    - ``usage.rst``

26. Show the changes before making a commit::

      git diff docs/

27. Commit the changes::

      git add docs/

      git commits -m "$ISSUE: Creating maintenance branch for release $NEW_VERSION."

28. Push the maintenance branch::

      git push origin "${NEW_VERSION%.*}"

29. Switch back to the master branch::

      git checkout master

30. Mark issues as resolved in the issue tracker.

31. Release the version via release center in the issue tracker.

32. Archive all other releases.

Releasing new patch version

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

New patch releases are based off of the specific maintenance branch ``HEAD``.

When releasing a new patch release, procedure is as follows:

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

2. Switch to the project Python virtual environment::

     workon majic-ansible-roles

3. Set the new version and issuer associated with making the release::

     NEW_VERSION="MAJOR.MINOR.PATCH"

     ISSUE="MAR-NUMBER"

4. Make sure you are on the maintenance branch for that version::

     git checkout "${NEW_VERSION%.*}"

5. Extract current version::

     CURRENT_VERSION=$(grep '^version = ' docs/conf.py | sed -e "s/^version = '//;s/'$//")

6. Double-check what the associated issues is, what the current version string

   is, and what the release version will be::

     echo "[$ISSUE] $CURRENT_VERSION -> $NEW_VERSION"

7. Create issue branch::

     git checkout -b "${ISSUE,,}"

8. Verify that documentation builds and looks correct::

     (cd docs/; make clean html; firefox _build/html/index.html)

9. Test deployment of test site from scratch to make sure all roles behave

   correctly.

10. Add release notes to file ``docs/releasenotes.rst``. Release notes template

    should be as follows::

      GENERAL DESCRIPTION

      Bug-fixes:

      * ``ROLE`` role

        * BUG-FIX DESCRIPTION

11. Clean-up the documentation build, and check what files need to be updated::

      (cd docs; make clean; grep -r "${CURRENT_VERSION/./\\.}" .)

12. Update all relevant documents with new version information, as obtained from

    the previous command. At the very least this includes changes to:

    - ``docs/conf.py``

    - ``usage.rst``

13. Ensure documentation builds correctly::

      (cd docs/; make clean html)

14. Show the changes before making a commit::

      git diff docs/

15. Commit the changes::

      git add docs/

      git commits -m "$ISSUE: Preparing for release $NEW_VERSION."

16. Create annotated and signed Git tag::

      git tag --sign -a "$NEW_VERSION" -m "RELEASE DESCRIPTION"

17. Clean-up the documentation build, check what files need to be switched back

    to maintenance version, and determine maintenance version::

     (cd docs; make clean; grep -r "${NEW_VERSION/./\\.}" .)

     echo "${NEW_VERSION%.*}-maint"

18. Update all relevant documents with maintenance version information, as

    obtained from the previous command. At the very least this includes changes

    to:

    - ``docs/conf.py``

    - ``usage.rst``

19. Show the changes before committing them::

      git diff docs/

20. Commit the changes::

      git add docs/

      git commits -m "$ISSUE: Bumping version to ${NEW_VERSION%.*}-maint (switching back to maintenance)."

20. Verify GnuPG signatures::

      git gpgcheck

      git verify-tag "$NEW_VERSION"

21. Merge changes back into the maintenance branch::

      git checkout "${NEW_VERSION%.*}

      git merge "${ISSUE,,}"

22. Push the tag and changes to mainteance branch::

      git push

      git push origin "${NEW_VERSION}"

23. Switch back to the master branch::

      git checkout master

24. Mark issues as resolved in the issue tracker.

25. Release the version via release center in the issue tracker.

26. Archive all old patch releases with the same major and minor number as new

    release version.