From 31e5dc64fc76366cbf28a7285ff0047857e8fe43 Mon Sep 17 00:00:00 2001
From: Amir MOHAMMADI <amir.mohammadi@idiap.ch>
Date: Wed, 15 Jun 2022 18:11:16 +0200
Subject: [PATCH] Update release instructions
---
doc/release.rst | 81 ++++++++++++++++++++++++++++++++-----------------
1 file changed, 54 insertions(+), 27 deletions(-)
diff --git a/doc/release.rst b/doc/release.rst
index 85dbaab2..9484d5cb 100644
--- a/doc/release.rst
+++ b/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``.
--
GitLab