Updated section "backward compatibility" in contributing.rst (#1918)

Co-authored-by: Alistair Sellar <[email protected]>
Co-authored-by: Bouwe Andela <[email protected]>
Co-authored-by: Rémi Kazeroni <[email protected]>

doc/changelog.rst

@@ -1,3 +1,5 @@
+.. _changelog:
+
 Changelog
 =========
 

doc/contributing.rst

@@ -139,6 +139,28 @@ The icons indicate whether the item will be checked during the
 - 🛠 The :ref:`list of authors <authors>` is up to date
 - 🛠 The :ref:`checks shown below the pull request <pull_request_checks>` are successful
 
+Pull requests introducing a change that causes a recipe to no longer run successfully
+(*breaking change*), or which results in scientifically significant changes in results
+(*science change*) require additional items to be reviewed defined in the
+:ref:`backward compatibility policy<esmvaltool:backward-compatibility-policy>`.
+These include in particular:
+
+- 🛠 Instructions for the release notes to assist *recipe
+  developers* to adapt their recipe in light of the *backward-incompatible change*
+  available.
+- 🛠 General instructions for *recipe developers* working on *user
+  recipes* to enable them to adapt their code related to
+  *backward-incompatible changes* available (see `ESMValTool_Tutorial: issue
+  #263 <https://github.com/ESMValGroup/ESMValTool_Tutorial/issues/263>`__).
+- 🛠 Core development team tagged to notify them of the
+  *backward-incompatible change*, and give at least
+  2 weeks for objections to be raised before merging to the main
+  branch. If a strong objection is raised the backward-incompatible
+  change should not be merged until the objection is resolved.
+- 🛠 Information required for the “*backward-incompatible changes*”
+  section in the PR  that introduces the *backward-incompatible change*
+  available.
+
 .. _scientific_relevance:
 
 Scientific relevance
@@ -558,6 +580,13 @@ there are also users who choose not to share their work there.
 While our commitment is first and foremost to users who do share their recipes
 in the ESMValTool repository, we still try to be nice to all of the ESMValCore
 users.
+
+.. note::
+
+   The :ref:`backward compatibility policy<esmvaltool:backward-compatibility-policy>`
+   outlines the key principles on backward compatibility and additional guidance on handling
+   *backward-incompatible changes*. This policy applies to both, ESMValCore and ESMValTool.
+
 When making changes, e.g. to the :ref:`recipe format <recipe_overview>`, the
 :ref:`diagnostic script interface <interfaces>`, the public
 :ref:`Python API <api>`, or the :ref:`configuration file format <config>`,
@@ -606,6 +635,11 @@ recipes in ESMValTool and link the ESMValTool pull request(s) in the ESMValCore
 pull request description.
 You can ask the `@ESMValGroup/esmvaltool-recipe-maintainers`_ for help with
 updating existing recipes, but please be considerate of their time.
+You should tag the `@ESMValGroup/esmvaltool-coreteam`_ to
+notify them of the backward-incompatible change, and give at least
+2 weeks for objections to be raised before merging to the main
+branch. If a strong objection is raised the backwards-incompatible
+change should not be merged until the objection is resolved.
 
 When reviewing a pull request, always check for backward incompatible changes
 and make sure they are needed and have been discussed with the
@@ -767,10 +801,18 @@ the release branch.
 4. Add release notes
 ~~~~~~~~~~~~~~~~~~~~
 Use the script
-:ref:`esmvaltool/utils/draft_release_notes.py <esmvaltool:draft_release_notes.py>`
+:ref:`esmvaltool/utils/draft_release_notes.py <draft_release_notes.py>`
 to create create a draft of the release notes.
 This script uses the titles and labels of merged pull requests since the
 previous release.
+Open a discussion to allow members of the development team to nominate pull 
+requests as highlights. Add the most voted pull requests as highlights at the 
+beginning of changelog. After the highlights section, list any backward 
+incompatible changes that the release may include. The 
+:ref:`backward compatibility policy<esmvaltool:backward-compatibility-policy>`.
+lists the information that should be provided by the developer of any backward 
+incompatible change. Make sure to also list any deprecations that the release 
+may include, as well as a brief description on how to upgrade a deprecated feature.
 Review the results, and if anything needs changing, change it on GitHub and
 re-run the script until the changelog looks acceptable.
 Copy the result to the file ``doc/changelog.rst``.