Merge branch 'master' into xtrig-arg-validate

.github/workflows/test_fast.yml

@@ -140,7 +140,7 @@ jobs:
         uses: actions/download-artifact@v4
 
       - name: Codecov upload
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           name: ${{ github.workflow }}
           flags: fast-tests

.github/workflows/test_functional.yml

@@ -316,7 +316,7 @@ jobs:
         uses: actions/download-artifact@v4
 
       - name: Codecov upload
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           name: ${{ github.workflow }}
           flags: functional-tests

README.md

@@ -29,28 +29,14 @@ domains.
 # install cylc
 conda install cylc-flow
 
-# write your first workflow
-mkdir -p ~/cylc-src/example
-cat > ~/cylc-src/example/flow.cylc <<__CONFIG__
-[scheduling]
-    initial cycle point = 1
-    cycling mode = integer
-    [[graph]]
-        P1 = """
-            a => b => c & d
-            b[-P1] => b
-        """
-[runtime]
-    [[a, b, c, d]]
-        script = echo "Hello $CYLC_TASK_NAME"
-__CONFIG__
+# extract an example to run
+cylc get-resources examples/integer-cycling
 
 # install and run it
-cylc install example
-cylc play example
+cylc vip integer-cycling  # vip = validate, install and play
 
 # watch it run
-cylc tui example
+cylc tui integer-cycling
 ```
 
 ### The Cylc Ecosystem

changes.d/5864.feat.md

@@ -0,0 +1 @@
+Reimplemented the `suite-state` xtrigger for interoperability with Cylc 7.

changes.d/5933.fix.md

@@ -0,0 +1 @@
+Fixed bug in `cylc broadcast` (and the GUI Edit Runtime command) where everything after a `#` character in a setting would be stripped out.

changes.d/5943.feat.md

@@ -0,0 +1 @@
+The `stop after cycle point` can now be specified as an offset from the inital cycle point.

changes.d/5956.break.md

@@ -0,0 +1 @@
+`cylc lint`: deprecated `[cylc-lint]` section in favour of `[tool.cylc.lint]` in `pyproject.toml`

cylc/flow/cfgspec/globalcfg.py

@@ -165,9 +165,17 @@
 
         Template variables can be used to configure handlers. For a full list
         of supported variables see :ref:`workflow_event_template_variables`.
+
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
     ''',
     'handler events': '''
         Specify the events for which workflow event handlers should be invoked.
+
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
     ''',
     'mail events': '''
         Specify the workflow events for which notification emails should
@@ -176,13 +184,21 @@
     'startup handlers': f'''
         Handlers to run at scheduler startup.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES}``startup handler``.
     ''',
     'shutdown handlers': f'''
         Handlers to run at scheduler shutdown.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES}``shutdown handler``.
@@ -191,6 +207,10 @@
         Handlers to run if the scheduler shuts down with error status due to
         a configured timeout or a fatal error condition.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES}``aborted handler``.
@@ -199,36 +219,60 @@
         Workflow timeout interval. The timer starts counting down at scheduler
         startup. It resets on workflow restart.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionadded:: 8.0.0
     ''',
     'workflow timeout handlers': '''
         Handlers to run if the workflow timer times out.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionadded:: 8.0.0
     ''',
     'abort on workflow timeout': '''
         Whether the scheduler should shut down immediately with error status if
         the workflow timer times out.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionadded:: 8.0.0
     ''',
     'stall handlers': f'''
         Handlers to run if the scheduler stalls.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES}``stalled handler``.
     ''',
     'stall timeout': f'''
         The length of a timer which starts if the scheduler stalls.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES}``timeout``.
     ''',
     'stall timeout handlers': f'''
         Handlers to run if the stall timer times out.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES}``timeout handler``.
@@ -237,6 +281,10 @@
         Whether the scheduler should shut down immediately with error status if
         the stall timer times out.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES}``abort on timeout``.
@@ -245,13 +293,21 @@
         Scheduler inactivity timeout interval. The timer resets when any
         workflow activity occurs.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES} ``inactivity``.
     ''',
     'inactivity timeout handlers': f'''
         Handlers to run if the inactivity timer times out.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES}``inactivity handler``.
@@ -260,6 +316,10 @@
         Whether the scheduler should shut down immediately with error status if
         the inactivity timer times out.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionchanged:: 8.0.0
 
            {REPLACES}``abort on inactivity``.
@@ -268,6 +328,10 @@
         How long to wait for intervention on restarting a completed workflow.
         The timer stops if any task is triggered.
 
+        .. seealso::
+
+           :ref:`user_guide.scheduler.workflow_events`
+
         .. versionadded:: 8.2.0
 
     '''

cylc/flow/cfgspec/workflow.py

@@ -539,14 +539,20 @@ def get_script_common_text(this: str, example: Optional[str] = None):
         ''')
         # NOTE: final cycle point is not a V_CYCLE_POINT to allow expressions
         # such as '+P1Y' (relative to initial cycle point)
-        Conf('final cycle point', VDR.V_STRING, desc='''
+        Conf('final cycle point', VDR.V_CYCLE_POINT_WITH_OFFSETS, desc='''
             The (optional) last cycle point at which tasks are run.
 
             Once all tasks have reached this cycle point, the
             workflow will shut down.
 
             This item can be overridden on the command line using
             ``cylc play --final-cycle-point`` or ``--fcp``.
+
+            Examples:
+
+            - ``2000`` - Shorthand for ``2000-01-01T00:00``.
+            - ``+P1D`` - The initial cycle point plus one day.
+            - ``2000 +P1D +P1Y`` - The year ``2000`` plus one day and one year.
         ''')
         Conf('initial cycle point constraints', VDR.V_STRING_LIST, desc='''
             Rules to allow only some initial datetime cycle points.
@@ -599,7 +605,7 @@ def get_script_common_text(this: str, example: Optional[str] = None):
 
                {REPLACES}``[scheduling]hold after point``.
         ''')
-        Conf('stop after cycle point', VDR.V_CYCLE_POINT, desc='''
+        Conf('stop after cycle point', VDR.V_CYCLE_POINT_WITH_OFFSETS, desc='''
             Shut down the workflow after all tasks pass this cycle point.
 
             The stop cycle point can be overridden on the command line using
@@ -612,7 +618,18 @@ def get_script_common_text(this: str, example: Optional[str] = None):
                choosing not to run that part of the graph. You can play
                the workflow and continue.
 
+            Examples:
+
+            - ``2000`` - Shorthand for ``2000-01-01T00:00``.
+            - ``+P1D`` - The initial cycle point plus one day.
+            - ``2000 +P1D +P1Y`` - The year ``2000`` plus one day and one year.
+
             .. versionadded:: 8.0.0
+
+            .. versionchanged:: 8.3.0
+
+               This now supports offsets (e.g. ``+P1D``) in the same way the
+               :cylc:conf:`[..]final cycle point` does.
         ''')
         Conf('cycling mode', VDR.V_STRING, Calendar.MODE_GREGORIAN,
              options=list(Calendar.MODES) + ['integer'], desc='''

cylc/flow/config.py

@@ -853,9 +853,16 @@ def process_stop_cycle_point(self) -> None:
         if stopcp_str is None:
             stopcp_str = self.cfg['scheduling']['stop after cycle point']
 
-        if stopcp_str is not None:
-            self.stop_point = get_point(stopcp_str).standardise()
-            if self.final_point and (self.stop_point > self.final_point):
+        if stopcp_str:
+            self.stop_point = get_point_relative(
+                stopcp_str,
+                self.initial_point,
+            ).standardise()
+            if (
+                self.final_point is not None
+                and self.stop_point is not None
+                and self.stop_point > self.final_point
+            ):
                 LOG.warning(
                     f"Stop cycle point '{self.stop_point}' will have no "
                     "effect as it is after the final cycle "

cylc/flow/etc/examples/1-hello-world/.validate

@@ -0,0 +1,23 @@
+#!/bin/bash
+# THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE.
+# Copyright (C) NIWA & British Crown (Met Office) & Contributors.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+set -eux
+
+ID="$(< /dev/urandom tr -dc A-Za-z | head -c6)"
+cylc vip --check-circular --no-detach --no-run-name --workflow-name "$ID"
+cylc lint "$ID"
+cylc clean "$ID"

cylc/flow/etc/examples/1-hello-world/flow.cylc

@@ -0,0 +1,13 @@
+[meta]
+    title = Hello World
+    description = """
+        A simple workflow which runs a single task (hello_world) once.
+    """
+
+[scheduling]
+    [[graph]]
+        R1 = hello_world
+
+[runtime]
+    [[hello_world]]
+        script = echo "Hello World!"

cylc/flow/etc/examples/1-hello-world/index.rst

@@ -0,0 +1,21 @@
+Hello World
+-----------
+
+.. admonition:: Get a copy of this example
+   :class: hint
+
+   .. code-block:: console
+
+      $ cylc get-resources examples/hello-world
+
+In the time honoured tradition, this is the minimal Cylc workflow:
+
+.. literalinclude:: flow.cylc
+   :language: cylc
+
+It writes the phrase "Hello World!" to standard output (captured to the
+``job.out`` log file).
+
+Run it with::
+
+   $ cylc vip hello-world

cylc/flow/etc/examples/2-integer-cycling/.validate

@@ -0,0 +1,23 @@
+#!/bin/bash
+# THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE.
+# Copyright (C) NIWA & British Crown (Met Office) & Contributors.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+set -eux
+
+ID="$(< /dev/urandom tr -dc A-Za-z | head -c6)"
+cylc vip --check-circular --no-detach --no-run-name --final-cycle-point=1 --workflow-name "$ID"
+cylc lint "$ID"
+cylc clean "$ID"