.. vim: set fileencoding=utf-8 :

.. _bob.devtools.release:


Release Management
------------------

This package offers tools to release (tag) packages that follow Bob's
development guidelines.  It automatically updates the ``README.rst`` file of
the package to setup the correct pointers for the release build and
documentation badges.  The tools are setup to ensure a changelog is provided
with each release.  The changelog can be autogenerated from merge-requests or
commits in the target package.


Usage
=====

Using these scripts is a 2-step process:

1. Generate a changelog using ``bdt gitlab changelog``
2. Tag a release using ``bdt gitlab release``

Use the ``--help`` flag in each command to learn more about each command.

.. warning::

   While *beta* builds of packages will use the beta version of this package,
   *stable* will look for the **latest stable** version of this package for
   their build configuration.

   To **correctly** produce a release, ensure a **STABLE** version of
   bob.devtools is properly released **before** you start tagging packages.
   The builds will then use such version of this package to enforce the correct
   build environment during the packaging.

   If you forget to properly tag this package before doing so you risk building
   against the wrong set of dependencies.


Manually update changelog
=========================

.. todo:: These instructions may be outdated!!

The changelog since the last release can be found in the file
``bob/devtools/data/changelog_since_last_release.md``. The structure is
documented as part of the help message of ``bdt gitlab release``. Read it.

To manually update the changelog, follow these guidelines:

    1. For each tag, summarize the commits into several descriptive lines.
       These summaries become tag descriptions and they should extend/update
       the existing tag description. Therefore, each line of the summary should
       also start with ``*`` character like the tag descriptions.
    2. The last tag name is called ``patch``. This indicates that a patch
       version of this package will be automatically updated during the next
       tag/release. You can change ``patch`` to ``minor`` or ``major``, and the
       package will be then tagged/released with either minor or major version
       bump.  You may also set an explicit tag to the package (e.g.
       ``v1.0.0``), which may be required if no tags are available yet on
       gitlab.
    3. Once all commits were changed to corresponding tag descriptions (no more
       lines start with ``-`` characters), this package is ready for release
       and you can continue to another package in the changelog.


Releasing the Bob meta package
==============================

.. todo:: These instructions may be outdated!!

Here are the instructions to release Bob meta package:

* Run:

  .. code-block:: sh

     $ bdt gitlab getpath bob/bob.nightlies order.txt
     $ bdt gitlab visibility order.txt

* Put the list of public packages in ../../bob/requirements.txt
* Run ``bdt gitlab changelog`` first:

  .. code-block:: sh

     $ bdt gitlab changelog ../../bob/requirements.txt bob_changelog.md

* Put the beta of version of the intended release version in
  ``../../bob/version.txt``

  * For example do ``$ echo 5.0.0b0 > version.txt`` for bob 5.0.0 release.
  * Commit only this change to master: ``$ git commit -m "prepare for bob 5 release" version.txt``

* Get the pinnings (``--bob-version`` needs to be changed):

  .. code-block:: sh

     $ bdt gitlab release -p bob -c bob_changelog.md --bob-version 5.0.0 -- TOKEN

* Put the pinnings below in requirements.txt and meta.yaml (like ``bob.buildout
  == 2.1.6``) and meta.yaml (like ``bob.buildout 2.1.6``)

  * Make sure you add ``  # [linux]`` to Linux only packages.

* Test the conda recipe:

  .. code-block:: sh

     $ cd ../../bob
     $ conda render -m ../bob.admin/gitlab/conda_build_config.yaml -c https://www.idiap.ch/software/bob/conda conda

* Update the badges and version.txt to point to this version of Bob.
* Commit, push and tag a new version manually:

  .. code-block:: sh

     $ git commit -am "Increased stable version to 4.0.0"
     $ git tag v4.0.0
     $ git push
     $ git push --tags

* Put ``bob_changelog.md`` inside bob's tag description.
* Cancel the pipeline for master and make sure that tag pipeline passes before
  continuing.
* Remove pinnings from bob's requirement.txt and meta.yaml and revert changes
  that went in ``README.rst`` back to master version.
* Commit and push the following (not verbatim):

  .. code-block:: sh

     $ echo 4.0.1b0 > version.txt
     $ git commit -am "Increased latest version to 4.0.1b0 [skip ci]"
     $ git push