From 50f550511d38142505aafbbdcce9dcf2690e063f Mon Sep 17 00:00:00 2001
From: Oliver Breitwieser <oliver.breitwieser@kip.uni-heidelberg.de>
Date: Thu, 22 Oct 2020 16:39:30 +0200
Subject: [PATCH] Document gerrit trigger keywords in README

Change-Id: I39ac48f7592cf55b9a1c6b1e76210456d19636f6
---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/README.md b/README.md
index be04c6a8..07758d67 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,49 @@
 # Yashchiki
 
 Visionary "containering"…
+
+## Supported keywords in gerrit message
+
+### `BUILD_THIS`
+
+Start a yashicki build with this change as toplevel.
+
+
+### `NO_FAILED_CACHE`
+
+If a testing build fails, link all preserved packages and the current build
+cache to a new temporary build cache under `failed/c<num>p<num>_<num>`.
+
+Behaviour for testing builds triggered from gerrit:
+* Unless the user specifies `NO_FAILED_CACHE` in the gerrit commit,
+  check if there is a failed build cache for this changeset that was
+  created as described above and use the latest one as build cache for
+  the current build.
+* The user can also supply `USE_CACHE_NAME=<name>` to specify a
+  different build cache to be used for this build.
+
+
+### `USE_CACHE_NAME=<name>`
+
+Use `/home/vis_jenkins/build_caches/<name>` on `conviz` as buildcache instead
+of the default one. Can also be used for failed caches.
+
+
+### `WITH_SPACK_{CHANGE,REFSPEC}`
+
+Since often times yashchiki and spack changes are tested together but
+have no real dependency on one another, we misuse the `Depends-On`
+mechanism in the commit message to build a container with a specific
+spack and yashchiki changeset.
+
+This changeset adds the possibility to specify:
+* `WITH_SPACK_CHANGE=<change-num>` to use the latest patch set of the
+  given spack changeset for the build
+* `WITH_SPACK_REFSPEC=<refspec>` to specify a complete spack refspec
+  that is to be used for this build (i.e.,
+  refs/changes/<change-num[-2:]>/<change-num>/<patch-level>) to have
+  full control over which changeset/patch level to build.
+
+These take priority over commit-specified `Depends-On:` and are mutually
+exclusive with jenkins-specified build parameters since each build gets
+either triggered manually in jenkins or via gerrit.
-- 
GitLab