From 727b7848cfbefdf0edff1b4e88e7445715c2ea1b Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Wed, 3 Jun 2026 11:53:12 +0100 Subject: [PATCH 1/3] remove documentation for Cylc 7 compatibility mode * See https://github.com/cylc/cylc-flow/pull/7325 --- .../major-changes/compatibility-mode.rst | 244 +----------------- src/7-to-8/major-changes/cylc-install.rst | 13 - src/7-to-8/major-changes/platforms.rst | 8 - src/7-to-8/major-changes/suicide-triggers.rst | 3 - src/7-to-8/summary.rst | 20 +- src/reference/changes.rst | 23 ++ src/tutorial/scheduling/graphing.rst | 3 - .../writing-workflows/scheduling.rst | 4 +- 8 files changed, 33 insertions(+), 285 deletions(-) diff --git a/src/7-to-8/major-changes/compatibility-mode.rst b/src/7-to-8/major-changes/compatibility-mode.rst index 4f0b6d0206..3ab945d4e0 100644 --- a/src/7-to-8/major-changes/compatibility-mode.rst +++ b/src/7-to-8/major-changes/compatibility-mode.rst @@ -3,241 +3,13 @@ Cylc 7 Compatibility Mode ========================= -.. warning:: +Cylc 8 initially provided a Cylc 7 compatibility mode which allowed workflows +to be run under either Cylc 7 or 8, to help facilitate migration. - Cylc 7 compatibility mode will be removed in Cylc 8.7.0, please upgrade - any workflows with "suite.rc" files. +This compatibility mode was removed in Cylc 8.7.0. If you have any workflows +that still use a ``suite.rc`` file, please skim through +:ref:`configuration-changes` then rename this file to ``flow.cylc`` and address +any errors/warnings. -.. admonition:: Does This Change Affect Me? - :class: tip - - This will affect you if you want to run Cylc 7 (``suite.rc``) workflows - using Cylc 8. - -Overview --------- - -Cylc 8 can run most Cylc 7 workflows "as is". -The ``suite.rc`` filename triggers a backward compatibility mode in which: - -- :term:`implicit tasks ` are allowed by default - - - (unless a ``rose-suite.conf`` file is found in the :term:`run directory` - for consistency with ``rose suite-run`` behaviour) - - (Cylc 8 does not allow implicit tasks by default) - -- :term:`cycle point time zone` defaults to the local time zone - - - (Cylc 8 defaults to UTC) - -- waiting tasks are pre-spawned to mimic the Cylc 7 scheduling algorithm and - stall behaviour, and these require - :term:`suicide triggers ` - for alternate :term:`graph branching` - - - (Cylc 8 spawns tasks on demand, and suicide triggers are not needed for - branching) - -- ``succeeded`` task outputs are :ref:`required `, - so in the absence of suicide triggers the scheduler will retain other - :term:`final status` tasks in the :term:`n=0 window ` to stall the - workflow. - - - (in Cylc 8, **all** outputs are *required* unless marked as - :ref:`*optional* ` by the new ``?`` syntax) - - -.. _compat_required_changes: - -Required Changes ----------------- - -Providing your Cylc 7 workflow does not use syntax that was deprecated at Cylc 7, -you may be able to run it using Cylc 8 without any modifications while in -compatibility mode. - -First, run ``cylc validate`` **with Cylc 7** on your ``suite.rc`` workflow -to check for deprecation warnings and fix those before validating with Cylc 8. -See :ref:`below ` for an example. - -.. warning:: - - ``cylc validate`` operates on the processed ``suite.rc``, which - means it will not detect any deprecated syntax that is inside a - currently-unused Jinja2 ``if...else`` branch. - -Some workflows may require modifications to either upgrade to Cylc 8 or make -interoperable with Cylc 8 backward compatibility mode. Read on for more details. - - -Cylc commands in task scripts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Check for any use of Cylc commands in task scripting. Some Cylc 7 commands -have been removed and some others now behave differently. -However, ``cylc message`` and ``cylc broadcast`` have *not* changed. -See the :ref:`full list of command line interface changes` -and see :ref:`below ` for an example. - - -Python 2 to 3 -^^^^^^^^^^^^^ - -Whereas Cylc 7 runs using Python 2, Cylc 8 runs using Python 3. This affects: -- modules imported in Jinja2 -- Jinja2 filters, tests and globals -- custom xtrigger functions - -Note that task scripts are not affected - they run in an independent -environment. - -See :ref:`py23` for more information and examples of how to implement -interoperability if your workflows extend Cylc or Jinja2 with custom Python scripts. - - -Other caveats -^^^^^^^^^^^^^ - -- Cylc 8 cannot *restart* a partially completed Cylc 7 workflow in-place. If - possible, complete the run with Cylc 7. Otherwise, see - :ref:`compat_continuing_c7_with_c8`. - -- Cylc 8 only transfers certain files and directories by default during - remote installation. See :ref:`728.remote-install` for more information. - -- Cylc 8 does not support - :ref:`excluding/including tasks at start-up`. - If your workflow used this old functionality, it may have been used in - combination with the ``cylc insert`` command (which has been removed from - Cylc 8) and ``cylc remove`` (which still exists but is much less needed). - -- Cylc 8 does not support :ref:`specifying remote usernames <728.remote_owner>` - using :cylc:conf:`flow.cylc[runtime][][remote]owner`. - - -Examples --------- - -.. _compat.eg.c7val: - -Validating with Cylc 7 -^^^^^^^^^^^^^^^^^^^^^^ - -Consider this configuration: - -.. code-block:: cylc - :caption: ``suite.rc`` - - [scheduling] - initial cycle point = 11000101T00 - [[dependencies]] - [[[R1]]] - graph = task - - [runtime] - [[task]] - pre-command scripting = echo "Hello World" - -Running ``cylc validate`` at **Cylc 7** we see that the -workflow is valid, but we are warned that ``pre-command scripting`` -was replaced by ``pre-script`` at 6.4.0: - -.. code-block:: console - :caption: Cylc 7 validation - - $ cylc validate . - WARNING - deprecated items were automatically upgraded in 'suite definition': - WARNING - * (6.4.0) [runtime][task][pre-command scripting] -> [runtime][task][pre-script] - value unchanged - Valid for cylc-7.8.7 - -.. note:: - - **Cylc 7** has handled this deprecation for us, but at **Cylc 8** this - workflow will fail validation. - - .. code-block:: console - :caption: Cylc 8 validation - - $ cylc validate . - IllegalItemError: [runtime][task]pre-command scripting - -You must change the configuration yourself. In this case: - -.. code-block:: diff - - - pre-command scripting = echo "Hello World" - + pre-script = echo "Hello World" - -Validation will now succeed. - - -.. _compat.eg.cylc-commands: - -Cylc commands in task scripts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You might have a task script that calls a Cylc command like so: - -.. code-block:: cylc - - [runtime] - [[foo]] - script = cylc hold "$CYLC_SUITE_NAME" - -The ``cylc hold`` command has changed in Cylc 8. It is now used for holding -tasks only; use ``cylc pause`` for entire workflows. -(Additionally, ``$CYLC_SUITE_NAME`` is deprecated in favour of -:envvar:`CYLC_WORKFLOW_ID`, though still supported.) - -In order to make this interoperable, so that you can run it with both Cylc 7 -and Cylc 8 backward compatibility mode, you could do something like this -in the bash script: - -.. code-block:: cylc - - [runtime] - [[foo]] - script = """ - if [[ "${CYLC_VERSION:0:1}" == 7 ]]; then - cylc hold "$CYLC_SUITE_NAME" - else - cylc pause "$CYLC_WORKFLOW_ID" - fi - """ - -Note this logic (and the :envvar:`CYLC_VERSION` environment variable) is -executed at runtime on the :term:`job host`. - -Alternatively, you could use :ref:`Jinja` like so: - -.. code-block:: cylc - - [runtime] - [[foo]] - {% if CYLC_VERSION is defined and CYLC_VERSION[0] == '8' %} - script = cylc pause "$CYLC_WORKFLOW_ID" - {% else %} - script = cylc hold "$CYLC_SUITE_NAME" - {% endif %} - -Note this logic (and the :envvar:`CYLC_VERSION` Jinja2 variable) is executed -locally prior to Cylc parsing the workflow configuration. - - -Renaming to ``flow.cylc`` -------------------------- - -When your workflow runs successfully in backward compatibility mode, it is -ready for renaming ``suite.rc`` to ``flow.cylc``. Doing this will turn off -backward compatibility mode, and validation in Cylc 8 will show -deprecation warnings. - -.. seealso:: - - :ref:`configuration-changes` - -.. important:: - - More complex workflows (e.g. those with suicide triggers) may - fail validation once backward compatibility is off - see - :ref:`728.optional_outputs` +For more information on what compatibility mode did, please see the +`Cylc 8.6 documentation `_. diff --git a/src/7-to-8/major-changes/cylc-install.rst b/src/7-to-8/major-changes/cylc-install.rst index 5ad51b6c3a..c4e7edbe6a 100644 --- a/src/7-to-8/major-changes/cylc-install.rst +++ b/src/7-to-8/major-changes/cylc-install.rst @@ -99,19 +99,6 @@ However, Cylc 8 will only copy the ``ana``, ``app``, ``bin``, ``etc`` and If you want to include custom files and directories in remote installation, use :cylc:conf:`flow.cylc[scheduler]install`. -.. tip:: - - If you need to ensure your workflow is still - :ref:`interoperable ` with Cylc 7, wrap it in a - Jinja2 check like so: - - .. code-block:: cylc - - {% if CYLC_VERSION is defined and CYLC_VERSION[0] == '8' %} - [scheduler] - install = my-dir/, my-file - {% endif %} - See :ref:`the user guide ` for more details. .. warning:: diff --git a/src/7-to-8/major-changes/platforms.rst b/src/7-to-8/major-changes/platforms.rst index d97f26dbb4..d2fc256154 100644 --- a/src/7-to-8/major-changes/platforms.rst +++ b/src/7-to-8/major-changes/platforms.rst @@ -43,14 +43,6 @@ suitable for a task. Such platforms can be set up to be ``platform groups`` :ref:`AdminGuide.PlatformConfigs` for detailed examples of platform configurations. -.. tip:: - - Cylc 8 contains upgrade logic (:ref:`see below `) - which handles the deprecated Cylc 7 settings in most cases. - Unless you are in :ref:`backward compatibility mode `, - you should upgrade to using platforms instead. - Deprecated settings will be removed in a later release of Cylc. - What is a Platform? ------------------- diff --git a/src/7-to-8/major-changes/suicide-triggers.rst b/src/7-to-8/major-changes/suicide-triggers.rst index c24e925b4c..9e51a742cc 100644 --- a/src/7-to-8/major-changes/suicide-triggers.rst +++ b/src/7-to-8/major-changes/suicide-triggers.rst @@ -21,9 +21,6 @@ the need for suicide triggers). This is called :term:`graph branching`. :term:`suicide triggers ` (marked by ``!`` before the task name in the graph, e.g. ``foo:fail => !foo``). - You should *not* perform this upgrade if still in :ref:`cylc_7_compat_mode` - (``suite.rc`` filename). - Required Changes ^^^^^^^^^^^^^^^^ diff --git a/src/7-to-8/summary.rst b/src/7-to-8/summary.rst index 5d25704d95..4c62a97447 100644 --- a/src/7-to-8/summary.rst +++ b/src/7-to-8/summary.rst @@ -21,20 +21,6 @@ Cylc now uses more widely understood terms for several core concepts. Note the configuration filename is now ``flow.cylc``, not ``suite.rc``. -Cylc 7 Compatibility Mode -------------------------- - -Continuing to use the old ``suite.rc`` filename triggers a :ref:`backward -compatibility mode` in Cylc 8 which supports Cylc 7 -workflow configurations out of the box, with -:ref:`some caveats `. However, to future-proof -your workflow and take full advantage of Cylc 8 you should upgrade to Cylc 8 syntax. - -.. warning:: - - Cylc 7 compatibility mode will be removed in Cylc 8.7.0. - - Upgrading To Cylc 8 ------------------- .. seealso:: @@ -47,9 +33,6 @@ To upgrade your Cylc 7 suite to a Cylc 8 workflow: #. Using Cylc 7, make sure the configuration validates (``cylc validate``) without any warnings. -#. Using Cylc 8 check that you can run the workflow. Running Cylc 8 with a - workflow configured with a ``suite.rc`` turns on - :ref:`compatibility mode `. #. Rename the workflow configuration file from ``suite.rc`` to ``flow.cylc``. #. Using Cylc 8 run ``cylc lint --ruleset 728`` and ``cylc validate``. Make sure that you deal with any warnings produced by these scripts. @@ -290,8 +273,7 @@ Queues we now recommend using queues to restrict the number of running tasks in situations where graphing may have been used previously. Time Zones - :cylc:conf:`[scheduler]cycle point time zone` now defaults to UTC, unless you - are working in :ref:`cylc_7_compat_mode`. + :cylc:conf:`[scheduler]cycle point time zone` now defaults to UTC. Job Scripts All user-defined task scripting now runs in a subshell, so you can safely switch Python environments inside tasks without affecting Cylc. diff --git a/src/reference/changes.rst b/src/reference/changes.rst index 3f77b41f06..c4b5ec6601 100644 --- a/src/reference/changes.rst +++ b/src/reference/changes.rst @@ -5,6 +5,29 @@ This page contains a summary of significant changes across all Cylc components f release. +Cylc 8.7 +-------- + + +.. admonition:: Cylc Components + :class: hint + + TODO! + + +Cylc 7 Compatibility Mode +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Cylc 7 compatibility mode (which allowed workflows to run under both Cylc 7 +and 8) has now been removed. + +See :ref:`cylc_7_compat_mode` for more details. + +As part of this change, the version of Jinja2 that Cylc uses has increased From +3.0 to 3.1+. As a result, any use of deprecated Jinja2 interfaces will likely +break with this Cylc release. + + Cylc 8.6 -------- diff --git a/src/tutorial/scheduling/graphing.rst b/src/tutorial/scheduling/graphing.rst index 9a39e22300..cd5dfdcf27 100644 --- a/src/tutorial/scheduling/graphing.rst +++ b/src/tutorial/scheduling/graphing.rst @@ -36,9 +36,6 @@ The :cylc:conf:`flow.cylc` File Format Prior to Cylc 8, :cylc:conf:`flow.cylc` was named ``suite.rc``, but that name is now deprecated. - See :ref:`cylc_7_compat_mode` for information on compatibility with - existing Cylc 7 ``suite.rc`` files. - Example ^^^^^^^ diff --git a/src/user-guide/writing-workflows/scheduling.rst b/src/user-guide/writing-workflows/scheduling.rst index 72053ccf8e..2c7d941be6 100644 --- a/src/user-guide/writing-workflows/scheduling.rst +++ b/src/user-guide/writing-workflows/scheduling.rst @@ -327,9 +327,7 @@ The time is assumed to be in UTC unless you set At Cylc 7 the time zone was assumed to be local time unless :cylc:conf:`[scheduler]cycle point time zone` or :cylc:conf:`[scheduler]UTC mode` - was set. If your workflow is running in - :ref:`Cylc 7 compatibility mode ` - this remains the case. + was set. The calendar is assumed to be the proleptic Gregorian calendar unless you set :cylc:conf:`[scheduling]cycling mode`. From 2741a083de4b4d15204f3a1961b4af8e357bf41c Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Thu, 11 Jun 2026 15:13:58 +0100 Subject: [PATCH 2/3] user guide: add section on cylc versions and compatibility --- src/reference/changes.rst | 2 + src/user-guide/running-workflows/index.rst | 1 + .../inter-version-compatibility.rst | 161 ++++++++++++++++++ 3 files changed, 164 insertions(+) create mode 100644 src/user-guide/running-workflows/inter-version-compatibility.rst diff --git a/src/reference/changes.rst b/src/reference/changes.rst index c4b5ec6601..e83439ecd2 100644 --- a/src/reference/changes.rst +++ b/src/reference/changes.rst @@ -1,3 +1,5 @@ +.. _reference.changes: + Changes ======= diff --git a/src/user-guide/running-workflows/index.rst b/src/user-guide/running-workflows/index.rst index af4cdd4898..13f523ad1a 100644 --- a/src/user-guide/running-workflows/index.rst +++ b/src/user-guide/running-workflows/index.rst @@ -17,3 +17,4 @@ Running Workflows authentication-files workflow-databases advanced + inter-version-compatibility diff --git a/src/user-guide/running-workflows/inter-version-compatibility.rst b/src/user-guide/running-workflows/inter-version-compatibility.rst new file mode 100644 index 0000000000..cbacf6c161 --- /dev/null +++ b/src/user-guide/running-workflows/inter-version-compatibility.rst @@ -0,0 +1,161 @@ +Upgrading Cylc Workflows and Inter-Version Compatibility +======================================================== + +Cylc is an active project, continually developing and evolving: + +* *"Minor"* versions of Cylc containing new features (e.g, ``8.1``, ``8.2``, + ``8.3``, etc) are typically released every 6-12 months. +* *"Maintainance"* versions of Cylc containing bugfixes (e.g, ``8.1.1``, + ``8.1.2``, ``8.1.3``, etc) are typically released every 2-10 weeks. + +The most important new developments in Cylc are listed on the +:ref:`reference.changes` page. We also announce these features on the +`Cylc Forum `_ to help you +stay up-to-date. + + +.. _user_guide.upgrading_running_workflows: + +Upgrading Running Workflows +--------------------------- + +Although Cylc workflows can run indefinitely, it is advisable to occasionally +upgrade running workflows to newer versions of Cylc. This helps ensure +workflows remain up-to date and aren't affected by any bugs fixed in more recent +releases as well as avoiding any security issues which may develop in older +software deployments. + +Upgrading a running workflow to a newer version of Cylc is generally as +simple as restarting it. + +An example of upgrading a workflow from Cylc 8.5.1 to 8.6.4 on the command +line: + +.. code-block:: console + + $ cylc version + 8.6.4 + + $ cylc get-workflow-version my-workflow + 8.6.1 + + $ cylc stop my-workflow + Command queued + + $ cylc play my-workflow + This workflow was previously run with 8.5.1. + This version of Cylc is 8.6.4. + Are you sure you want to upgrade from 8.5.1 to 8.6.4?: y,n? y + + ▪ ■ Cylc Workflow Engine 8.6.4 + ██ Copyright (C) 2008-2026 NIWA + ▝▘ & British Crown (Met Office) & Contributors + +``cylc version`` + Tells you what version of Cylc you are currently working with. +``cylc get-workflow-version`` + Tells you what version of Cylc a workflow is currently running under. +``cylc stop --now --now`` + Stops the workflow, note the ``--now --now`` tells Cylc to shut down + immediately, rather than wait for active jobs to complete or workflow + event handlers to run. Cylc will automatically reconnect to running jobs + when the workflow is restarted. +``cylc play`` + Restarts the workflow. You can add the ``--upgrade`` argument to bypass + the interactive prompt. + + +.. _user_guide.deprecation_notices: + +Deprecation Notices +------------------- + +Some older Cylc features will become deprecated. + +If a workflow uses deprecated features warnings will be emitted, typically +when the workflow is validated / started. These may also appear in the GUI. + +An example of a workflow which uses features which are deprecated, but still +supported, in Cylc 8.6.4: + +.. code-block:: console + + $ cylc validate . + WARNING - Deprecated config items were automatically upgraded. Please alter your workflow to use the new syntax. + WARNING - * (8.0.0) [cylc][parameters] -> [task parameters] - value unchanged + WARNING - * (8.0.0) [cylc] -> [scheduler] - value unchanged + WARNING - deprecated settings found (please replace with [runtime][install]platform): + [runtime][install][remote]host = my-hpc + [runtime][install][job]batch system = pbs + Valid for cylc-8.6.4 + +Deprecated features will be removed in future versions of Cylc. + +Please take action on deprecation warnings to ensure the workflow can still +be run with newer versions of Cylc when they are released. + +For example, to address the first warning above: + +.. code-block:: none + + [cylc][parameters] -> [task parameters] - value unchanged + +You would need to make a change like this to the workflow's configuration: + +.. code-block:: diff + + - [cylc] + - [[parameters]] + - site = ukmo, esnz, bom + + + [task parameters] + + site = ukmo, esnz, bom + +.. note:: + + For more information on the format of these warnings, see the + :ref:`Cylc file format ` notes in the tutorial. + +.. tip:: + + The ``cylc lint`` tool can be helpful in detecting deprecated features and + other issues. If your workflow project is hosted on GitHub, you can use the + `setup-cylc `_ action to automate this + check. + + +.. _user_guide.inter_version_compatibility: + +Inter-Version Compatibility +--------------------------- + +Cylc clients (i.e, the GUI, Tui and command line) will still work with +workflows running with older or newer versions of Cylc, however, there are some +limits on how different these versions can be. + +Backwards Compatibility +^^^^^^^^^^^^^^^^^^^^^^^ + +We aim for a four minor-version compatibility window between running workflows +and **newer** Cylc clients. + +For example, if a workflow is running under Cylc 8.6.0, we would expect to be +able to view and interact with this workflow using **newer** versions of the +GUI, Tui or command line until 8.10.0 (which would be the first to break +compatibility). + +This isn't a firm guarantee and some functionality may be reduced. + + +Forwards Compatibility +^^^^^^^^^^^^^^^^^^^^^^ + +We aim for at least a one minor-version compatibility window between running +workflows and **older** Cylc clients. + +For example, if a workflow is running under 8.7.0, we would expect to be able +to view and interact with this workflow using **older** versions of the GUI, +Tui or command line back to Cylc 8.6.0. + +For the best support, you are encouraged to always use the most recent Cylc +client. From 8c0cfd43d3e375fa4dc94bb9a5f3dac0b0e5a044 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Thu, 11 Jun 2026 15:20:40 +0100 Subject: [PATCH 3/3] dictionary --- src/dictionaries/words | 1 + 1 file changed, 1 insertion(+) diff --git a/src/dictionaries/words b/src/dictionaries/words index b16eb23642..aeba9e7987 100644 --- a/src/dictionaries/words +++ b/src/dictionaries/words @@ -13,6 +13,7 @@ baz boolean booleans broadcasted +bugfixes cfg changelog changelogs