From 8a893a74247e502ca728ed8b726476bb32976832 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Wed, 15 Jul 2026 10:43:00 +0100 Subject: [PATCH 1/2] changes: global template variables --- src/reference/changes.rst | 53 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/src/reference/changes.rst b/src/reference/changes.rst index e83439ecd2..83be6ffb1c 100644 --- a/src/reference/changes.rst +++ b/src/reference/changes.rst @@ -30,6 +30,59 @@ As part of this change, the version of Jinja2 that Cylc uses has increased From break with this Cylc release. +"Global" Template Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Template variables, aka Jinja2 variables for use in the ``flow.cylc`` file, +may now be configured in the ``global.cylc`` file for automatic use in all +workflows. + +The intention of this feature is to allow site-specific variables to be +configured to facilitate workflow portability. + +This has overlap with the +:rose:conf:`rose.conf[rose-stem]automatic-options=SITE` Rose configuration +which sets a template variable called ``SITE`` for use in rose-stem test +suites. We would encourage all sites using this configuration to copy it +over to the ``global.cylc`` file to facilitate rose-stem migration. + +I.e, if you currently configure this: + +.. code-block:: ini + + # rose.conf + + [rose-stem] + automatic-options=SITE=my-site + +Then additionally configure this: + +.. code-block:: cylc + + # global.cylc + + [template variables] + SITE = my-site + +The Cylc configuration is more generic as it can be used in all workflows +(not just rose-stem suites). The Rose configuration remains supported and may +be left in place for back-compatibility with rose-stem workflows running under +Cylc 8.6. + +.. warning:: + + The `global.cylc[template variables]` configuration was only added in + Cylc 8.7.0 and was not present in earlier versions of Cylc where it would + cause errors if defined. + + To configure this only for Cylc 8.7 (to avoid errors with older versions of + Cylc) place the config in ``/flow/8.7/global.cylc`` + (you may want to do the same for 8.8, etc, until 8.6 is retired). + + For more information, see `global.cylc` and + ``cylc config --print-hierarchy``. + + Cylc 8.6 -------- From 10fe81635069b9015de08da0ce07a8d6388e53b2 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Wed, 26 Aug 2026 10:11:56 +0100 Subject: [PATCH 2/2] switch "rose:conf" for a hyperlink --- src/reference/changes.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/reference/changes.rst b/src/reference/changes.rst index 83be6ffb1c..7a86ee6440 100644 --- a/src/reference/changes.rst +++ b/src/reference/changes.rst @@ -33,6 +33,8 @@ break with this Cylc release. "Global" Template Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _rose.conf[rose-stem]automatic-options=SITE: https://metomi.github.io/rose/doc/html/api/configuration/site-and-user.html#rose:conf:rose.conf[rose-stem]automatic-options + Template variables, aka Jinja2 variables for use in the ``flow.cylc`` file, may now be configured in the ``global.cylc`` file for automatic use in all workflows. @@ -41,7 +43,7 @@ The intention of this feature is to allow site-specific variables to be configured to facilitate workflow portability. This has overlap with the -:rose:conf:`rose.conf[rose-stem]automatic-options=SITE` Rose configuration +`rose.conf[rose-stem]automatic-options=SITE`_ Rose configuration which sets a template variable called ``SITE`` for use in rose-stem test suites. We would encourage all sites using this configuration to copy it over to the ``global.cylc`` file to facilitate rose-stem migration.