Update release instructions

doc/release.rst

@@ -7,20 +7,23 @@ 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.
+development guidelines.  It automatically updates the ``README.rst`` and
+``version.txt`` files of the package to setup the correct version and 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:
+Releasing Bob is a 4-step process:
 
-1. Generate a changelog using ``bdt gitlab changelog``
+1. Generate a changelog using ``bdt gitlab changelog``.
+   * remove ``bob/bob`` from the changelog if it is present.
 2. Tag a release using ``bdt gitlab release``
+3. Release ``bob/bob`` manually.
+4. Release ``bob/docs`` manually.
 
 Use the ``--help`` flag in each command to learn more about each command.
 
@@ -36,16 +39,14 @@ Use the ``--help`` flag in each command to learn more about each command.
    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.
+   against the **wrong set of dependencies**.
 
 
-Manually update changelog
-=========================
+Generate the 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
+After generating a ``changelog.md`` file using the ``bdt gitlab changelog``
+command, you must edit the file manually. The structure of the file is
 documented as part of the help message of ``bdt gitlab release``. Read it.
 
 To manually update the changelog, follow these guidelines:
@@ -66,6 +67,24 @@ To manually update the changelog, follow these guidelines:
        and you can continue to another package in the changelog.
 
 
+.. note::
+
+   Remove the ``bob/bob`` line and its associated lines from the changelog if it
+   is present. This package must be released manually.
+
+.. warning::
+
+   Identifying the correct version of each package is important. We follow
+   semantic versioning (see https://semver.org/). Even if there are small
+   breaking changes in the package, we should always bump the major version. Our
+   conda packages rely on that.
+
+Release the Package(s)
+======================
+
+Use the ``bdt gitlab release`` command to tag the release of each package. This
+process is automatic but will take a long time to finish.
+
 Releasing the Bob meta package
 ==============================
 
@@ -85,8 +104,11 @@ Here are the instructions to release Bob meta package:
   .. code-block:: yaml
 
      - bob.ip.binseg ==1.1.0  # [linux]
+     - bob.bio.face ==7.0.0  # [not arm64]
 
-* Test the conda recipe of bob. You may want to cancel the command below once
+  Use ``git diff`` to make sure you have preserved the comments.
+
+* Test the conda recipe of bob. You may want to *cancel* the command below once
   it reaches the unit tests:
 
   .. code-block:: sh
@@ -106,19 +128,20 @@ Here are the instructions to release Bob meta package:
 
   .. code-block:: sh
 
-     $ bdt gitlab release -vvv CHANGELOG --package bob/bob
+     $ bdt gitlab release -vvv changelog.md --package bob/bob
 
 * When the script says ``Waiting for the pipeline *** of "bob/bob" to finish``, you may
   cancel it and check the progress online.
 
-* To revert the pins while in beta run:
+* You must revert the pins while in beta run:
 
   .. code-block:: sh
 
      $ git pull --rebase
      $ bdt gitlab update-bob -vvv --beta
 
-* Like before, **tag the linux only packages manually**.
+* Like before, **tag the linux only or intel only packages manually** and make
+  sure to preserve the comments.
 
 * Commit and push the changes:
 
@@ -127,15 +150,19 @@ Here are the instructions to release Bob meta package:
      $ git commit -m "Remove package pins while in beta. [skip ci]" conda/meta.yaml requirements.txt
      $ git push
 
-You can see that if we could identify linux only packages automatically, the whole
-release process would have been only to run
-``bdt gitlab release -vvv CHANGELOG --package bob/bob``.
-Do you want to help fix that?
+You can see that if we could have preserved the comments automatically, the
+whole release process would have been only to run ``bdt gitlab release -vvv
+changelog.md --package bob/bob`` given that we call ``bdt gitlab update-bob``
+inside that command. Do you want to help fix that?
+
+* Finally, manually edit the tag description of ``bob/bob`` and write a small
+  summary of major changes of this release. Similar to:
+  https://gitlab.idiap.ch/bob/bob/-/tags/v9.0.0
 
 
-Releasing the docs meta package
-===============================
+Release the docs meta package
+=============================
 
-Don't forget to release ``bob/docs`` after the bob release has successfully finished.
-To do so, go to https://gitlab.idiap.ch/bob/docs/-/tags and click on ``New tag``.
-Use the same version number you used for bob.
+Don't forget to release ``bob/docs`` after the bob release has successfully
+finished. To do so, just go to https://gitlab.idiap.ch/bob/docs/-/tags and click
+on ``New tag``. Use the same version number you used for ``bob/bob``.