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 using version ``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, *Majic Ansible Roles* employs a specific
nomenclature for naming the branches:

- All new development and bug-fixing uses master branch as the base.
- Features and bug-fixes are implemented in a local branch based on the master
  branch. Local branches are named after the lower-cased issue number. 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 (for sharing etc).
- 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).


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. 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 (cherry-picking if
   possible) the fix into maintenace branch. Make sure to resign (cherry-picking
   invalidates signature) and reword (to reference the backport issue) the
   commit.


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 '^release = ' docs/conf.py | sed -e "s/^release = '//;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 all roles using `Molecule <https://molecule.readthedocs.io/>`_ to make
   sure no regressions were introduced::

     ./scripts/run_tests.sh -r all

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::

      VERSION
      -------

      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

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 commit -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 development version, and determine development version::

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

18. 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``

19. Show the changes before committing them::

      git diff docs/

20. Commit the changes::

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

21. Verify GnuPG signatures::

      git gpgcheck
      git verify-tag "$NEW_VERSION"

22. Merge changes back into the master branch::

      git checkout master
      git merge "${ISSUE,,}"
      
23. Push the tag and changes to master::

      git push
      git push origin "${NEW_VERSION}"

24. Create the maintenace branch::

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

25. 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"

26. 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``

27. Show the changes before making a commit::

      git diff docs/

28. Commit the changes::

      git add docs/
      git commit -m "$ISSUE: Creating maintenance branch for release $NEW_VERSION."

29. Push the maintenance branch::

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

30. Switch back to the master branch::

      git checkout master

31. Delete the local branch::

      git branch -d "${ISSUE,,}"

32. Mark issue as resolved in the issue tracker.

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

34. 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 all roles using `Molecule <https://molecule.readthedocs.io/>`_ to make
   sure no regressions were introduced::

     ./scripts/run_tests.sh -r all

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

11. Add release notes to file ``docs/releasenotes.rst``. Release notes template
    should be as follows::

      VERSION
      -------

      GENERAL DESCRIPTION

      Bug-fixes:

      * ``ROLE`` role

        * BUG-FIX DESCRIPTION

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

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

13. 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``

14. Ensure documentation builds correctly::

      (cd docs/; make clean html)

15. Show the changes before making a commit::

      git diff docs/

16. Commit the changes::

      git add docs/
      git commit -m "$ISSUE: Preparing for release $NEW_VERSION."

17. Create annotated and signed Git tag::

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

18. 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"

19. 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``

20. Show the changes before committing them::

      git diff docs/

21. Commit the changes::

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

22. Verify GnuPG signatures::

      git gpgcheck
      git verify-tag "$NEW_VERSION"

23. Merge changes back into the maintenance branch::

      git checkout "${NEW_VERSION%.*}"
      git merge "${ISSUE,,}"
      
24. Push the tag and changes to mainteance branch::

      git push
      git push origin "${NEW_VERSION}"

25. Delete the local branch::

      git branch -d "${ISSUE,,}"

26. Switch back to the master branch::

      git checkout master

27. Mark issue as resolved in the issue tracker.

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

29. Archive all old patch releases with the same major and minor number as new
    release version.