changes: group trigger

Author: oliver-sanders

src/7-to-8/cheat-sheet.rst

@@ -331,7 +331,6 @@ Set task outputs:
 
          cylc set --out=succeeded
 
-
 Insert a task:
 
 .. list-table::
@@ -343,3 +342,19 @@ Insert a task:
 
          cylc insert
      - Tasks are inserted automatically when you "trigger" or "set" them.
+
+Re-run a group of tasks in order:
+
+.. list-table::
+   :class: grid-table
+
+   * - **Cylc 7**
+     - **Cylc 8**
+   * - ::
+
+         # reset the task to waiting, they will then re-run in order
+         cylc reset -s=waiting cycle1/task1 cycle2/task2 ...
+     - ::
+
+         # trigger the tasks in a single command, they will re-run in order
+         cylc trigger cycle1/task1 cycle2/task2 ...

src/reference/changes.rst

@@ -37,6 +37,32 @@ Cylc 8.5
    :rose: `2.4 <https://github.com/metomi/rose/blob/master/CHANGES.md>`__
 
 
+Triggering Multiple Tasks
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Cylc now respects the dependencies between tasks when triggering multiple
+tasks at the same time. This provides an easy way to re-run a group of tasks
+in order:
+
+.. image:: ../reference/changes/group-trigger.gif
+   :align: center
+   :width: 65%
+
+|
+
+This is generally easier than :ref:`using a new flow <interventions.reflow>`.
+
+Technical details:
+
+* Prerequisites on any tasks that are outside of the group of tasks being
+  triggered are automatically satisfied.
+* Any tasks which have already run within the group will be automatically
+  removed (i.e. ``cylc remove``) to allow them to be re-run without
+  intervention.
+* Any preparing, submitted or running tasks within the group will also be
+  removed if necessary to allow the tasks to re-run in order.
+
+
 Compatibility Mode
 ^^^^^^^^^^^^^^^^^^
 
@@ -65,6 +91,7 @@ to change which tool is used.
    Make sure your configured command waits for the tool to be closed before
    exiting, e.g. use ``GEDITOR=gvim -f`` rather than ``EDITOR=gvim``.
 
+
 Cylc Reload
 ^^^^^^^^^^^
 

src/reference/changes/group-trigger.gif

@@ -88,12 +88,48 @@ Re-Run a Task
          $ cylc trigger <workflow>//<task>
 
 
+.. _interventions.re-run-multiple-tasks:
+
 Re-Run Multiple Tasks
 ---------------------
 
 :Example:
-   I need to make changes to a task, then re-run it and everything downstream
-   of it.
+   I need to re-run a few tasks in order.
+
+:Solution:
+   Determine the tasks you want to re-run and trigger all of them at the
+   same time.
+
+   We often want to
+   :ref:`edit the tasks configuration <interventions.edit-a-tasks-configuration>`
+   before doing this.
+
+.. tab-set::
+
+   .. tab-item:: GUI
+      :sync: gui
+
+      .. image:: ./../../reference/changes/group-trigger.gif
+         :width: 75%
+
+   .. tab-item:: CLI
+      :sync: gui
+
+      .. code-block:: console
+
+         $ cylc trigger <workflow>// \
+         >   //<cycle-1>/<task-2> \
+         >   //<cycle-2>/<task-2> \
+         >   ...
+
+
+.. _interventions.reflow:
+
+Re-Run A Task And Everything After It
+-------------------------------------
+
+:Example:
+   I want to reconfigure a task, then re-run it and all tasks downstream of it.
 
 :Solution:
    :ref:`Edit the tasks configuration <interventions.edit-a-tasks-configuration>`,
@@ -104,7 +140,7 @@ Re-Run Multiple Tasks
    .. tab-item:: GUI
       :sync: gui
 
-      .. image:: re-run-multiple-tasks.gui.gif
+      .. image:: reflow.gui.gif
          :width: 75%
 
    .. tab-item:: CLI
@@ -114,6 +150,17 @@ Re-Run Multiple Tasks
 
          $ cylc trigger --flow=new <workflow>//<cycle>/<task>
 
+.. warning::
+
+   Be aware that tasks which have previously run, will not have run in the
+   new flow. As a result, you may want to manually set task outputs to allow
+   the new flow to continue.
+
+   You can achieve this by setting the
+   :ref:`outputs <interventions.set-task-outputs>` of these tasks, or
+   satisfying the :ref:`prerequisites <interventions.set-task-prerequisites>`
+   of the tasks in the new flow.
+
 
 Re-Run All Failed Tasks
 -----------------------