From b845bbc01d0d55c62c00f89f11765ebc88231e44 Mon Sep 17 00:00:00 2001
From: Paul Bauer <paul.bauer.q@gmail.com>
Date: Thu, 4 Jun 2020 14:58:59 +0000
Subject: [PATCH] Add ability to chose regressiontest commit and branch

Change-Id: I4b51a2c1a0ea434dc4c6d306ba88768ba8032270
---
 admin/gitlab-ci/archive.gitlab-ci.yml | 11 ++++++++-
 docs/dev-manual/gitlab.rst            | 33 +++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/admin/gitlab-ci/archive.gitlab-ci.yml b/admin/gitlab-ci/archive.gitlab-ci.yml
index 6c71b7a6d7..39fd0e2ba9 100644
--- a/admin/gitlab-ci/archive.gitlab-ci.yml
+++ b/admin/gitlab-ci/archive.gitlab-ci.yml
@@ -36,6 +36,15 @@ regressiontests:prepare:
   # Always clone the default version for this branch, master in this case
   script:
     - export REGTESTBRANCH=master
+    - if [[ -z $REGRESSIONTESTBRANCH ]] ; then
+      export REGTESTBRANCH=$REGRESSIONTESTBRANCH ;
+      echo "Using $REGTESTBRANCH instead of default" ;
+      fi
+    - export CHECKOUTCOMMIT=FETCH_HEAD
+    - if [[ ! -z $REGRESSIONTESTCOMMIT ]] ; then
+      export CHECKOUTCOMMIT=$REGRESSIONTESTCOMMIT ;
+      echo "Using $CHECKOUTCOMMIT instead of head of $SOURCEBRANCH" ;
+      fi
     - if [[ ! -d regressiontests ]] ; then
         mkdir regressiontests ;
         cd regressiontests ;
@@ -44,7 +53,7 @@ regressiontests:prepare:
       fi
     - cd regressiontests
     - git fetch https://gitlab.com/gromacs/gromacs-regressiontests.git $REGTESTBRANCH
-    - git checkout -qf FETCH_HEAD
+    - git checkout -qf $CHECKOUTCOMMIT
     - git clean -ffdxq
     - git gc
     - git archive -o gmx-regressiontests.tar.gz --prefix regressiontests/ -9 HEAD
diff --git a/docs/dev-manual/gitlab.rst b/docs/dev-manual/gitlab.rst
index 51852c3f4f..734f28b7b6 100644
--- a/docs/dev-manual/gitlab.rst
+++ b/docs/dev-manual/gitlab.rst
@@ -156,6 +156,21 @@ basic job name from qualifiers or details. Also consider
 
 .. _variables:
 
+Updating regression tests
+~~~~~~~~~
+
+Changes in |GROMACS| that require changes in regression-tests are notoriously hard,
+because a merge request that tests against the non-updated version of the
+regression tests will necessarily fail, while updating regression tests while
+the current change is not integrated into master, might cause other
+merge request pipelines to fail.
+
+The solution is a new regression-test branch or commit, uploaded to gitlab.
+Then set that regression test branch with REGRESSIONTESTBRANCH or
+the specific commit with REGRESSIONTESTCOMMIT when
+running the specific pipeline that requires the regressiontest-update. 
+See below on how to set variables for specific pipelines.
+
 Variables
 ~~~~~~~~~
 
@@ -209,5 +224,23 @@ Other important variable keys are as follows.
         patch to the base Docker images to include the dependency to reduce
         pipeline execution time.
 
+    REGRESSIONTESTBRANCH
+        Use this branch of the regressiontests rather than master to allow for 
+        merge requests that require updated regression tests with valid CI tests.
+
+    REGRESSIONTESTCOMMIT
+        Use this commit to the regressiontests rather than the head on master to 
+        allow for merge requests that require updated regression tests with 
+        valid CI tests.
+
+
 .. todo:: Define common variables.
     ``BUILD_DIR``, ``INSTALL_DIR``, ``CACHE_FALLBACK_KEY``, ...
+
+Setting variables
+~~~~~~~~~
+
+Variables for individual piplelines are set in the gitlab interface under 
+``CI/CD``&rarr;``Pipelines``. Then chose in the top right corner ``Run Piplelines``.
+Under ``Run for``, the desired branch may be selected, and variables may be set
+in the fields below.
\ No newline at end of file
-- 
2.22.0