From 2de1a2a8f6114b9d9ad13082dc73584b9bbb9cda Mon Sep 17 00:00:00 2001
From: Klaus Zimmermann <klaus.zimmermann@smhi.se>
Date: Thu, 13 Jul 2023 10:32:14 +0200
Subject: [PATCH] Add merge instructions to release instructions (#2131)

---
 doc/contributing.rst | 36 +++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/doc/contributing.rst b/doc/contributing.rst
index de87f76c66..8201fac707 100644
--- a/doc/contributing.rst
+++ b/doc/contributing.rst
@@ -833,7 +833,37 @@ and create the new release from the release branch (i.e. not from ``main``).
 
 Create a tag and tick the `This is a pre-release` box if working with a release candidate.
 
-6. Create and upload the PyPI package
+6. Mark the release in the main branch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the (pre-)release is tagged, it is time to merge the release branch back into `main`.
+We do this for two reasons, namely, one, to mark the point up to which commits in `main`
+have been considered for inclusion into the present release, and, two, to inform
+setuptools-scm about the version number so that it creates the correct version number in
+`main`.
+However, unlike in a normal merge, we do not want to integrate any of the changes from the
+release branch into main.
+This is because all changes that should be in both branches, i.e. bug fixes, originate from
+`main` anyway and the only other changes in the release branch relate to the release itself.
+To take this into account, we perform the merge in this case on the command line using `the
+ours merge strategy <https://git-scm.com/docs/merge-strategies#Documentation/merge-strategies.txt-ours-1>`__
+(``git merge -s ours``), not to be confused with the ``ours`` option to the ort merge strategy
+(``git merge -X ours``).
+For details about merge strategies, see the above-linked page.
+To execute the merge use following sequence of steps
+
+.. code-block:: bash
+
+   git fetch
+   git checkout main
+   git pull
+   git merge -s ours v2.1.x
+   git push
+
+Note that the release branch remains intact and you should continue any work on the release
+on that branch.
+
+7. Create and upload the PyPI package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The package is automatically uploaded to the
@@ -864,7 +894,7 @@ Follow these steps to create a new Python package:
 You can read more about this in
 `Packaging Python Projects <https://packaging.python.org/tutorials/packaging-projects/>`__.
 
-7. Create the Conda package
+8. Create the Conda package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``esmvalcore`` package is published on the `conda-forge conda channel
@@ -893,7 +923,7 @@ conda-forge some time later.
 Contact the feedstock maintainers if you want to become a maintainer yourself.
 
 
-8. Check the Docker images
+9. Check the Docker images
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 There are two main Docker container images available for ESMValCore on