Merge pull request #614 from cylc/8.1.x

8.1.x

Author: oliver-sanders

CONTRIBUTING.md

@@ -53,6 +53,7 @@ requests_).
  - Alex Pletzer
  - Yinjing Lin
  - David Sutherland
+ - Thomas Coleman
 <!-- end-shortlog -->
 
 (All contributors are identifiable with email addresses in the git version

src/7-to-8/major-changes/parameters.rst

@@ -0,0 +1,100 @@
+Parameters
+==========
+
+.. admonition:: does this change affect me?
+   :class: tip
+
+   If you use Cylc parameters with negative offsets (e.g. ``foo<x-1>``).
+
+
+Overview
+--------
+
+There has been a subtle change in the way negative offsets are handled in parameters.
+
+
+Example
+-------
+
+If you have a parameter ``x`` with the values 1, 2 & 3:
+
+.. code-block:: cylc
+
+   [task parameters]
+      x = 1..3
+
+And use it like so:
+
+.. code-block:: cylc-graph
+
+   a<x-1> => b<x> => c<x>
+
+There is some ambiguity about how this should be interpreted when ``x=1``
+because ``<x-1>`` would be ``0`` which is not a valid value for the parameter
+``x``.
+
+Cylc 7 removed the part of the expression which was out of range resulting in a
+partial evaluation of that line:
+
+.. code-block:: cylc-graph
+
+           b_x1 => c_x1  # x=1
+   a_x1 => b_x2 => c_x2  # x=2
+   a_x2 => b_x3 => c_x3  # x=3
+
+Whereas Cylc 8 will remove everything after the first out-of-range parameter - ``<x-1>`` (so the entire line for this example):
+
+.. code-block:: cylc-graph
+
+   a_x1 => b_x2 => c_x2  # x=2
+   a_x2 => b_x2 => c_x2  # x=3
+
+
+Migration
+---------
+
+If your workflow depends on the Cylc 7 behaviour, then the solution is
+to break the expression into two parts which Cylc will then evaluate separately.
+
+.. code-block:: diff
+
+   - a<x-1> => b<x> => c<x>
+   + a<x-1> => b<x>
+   + b<x> => c<x>
+
+Resulting in:
+
+.. code-block:: cylc-graph
+   
+   # a<x-1> => b<x>
+   a_x1 => a_x2  # x=2
+   a_x2 => a_x3  # x=3
+
+   # b<x> => c<x> 
+   b_x1 => c_x1  # x=1
+   b_x2 => c_x2  # x=2
+   b_x3 => c_x3  # x=3
+
+
+Line Breaks
+-----------
+
+Note that these expressions are all equivalent:
+
+.. list-table::
+   :class: grid-table
+
+   * - .. code-block::
+
+          a<x-1> => b<x> => c<x>
+
+     - .. code-block::
+
+          a<x-1> =>
+          b<x> =>
+          c<x>
+
+     - .. code-block::
+
+          a<x-1> => b<x> => \
+          c<x>

src/user-guide/task-implementation/job-scripts.rst

@@ -189,7 +189,7 @@ Task messages are validated by
 Aborting Job Scripts on Error
 -----------------------------
 
-Job scripts use ``set -x`` to abort on any error, and trap ERR, EXIT, and
+Job scripts use ``set -e`` to abort on any error, and trap ERR, EXIT, and
 SIGTERM to send task failed messages back to the :term:`scheduler` before
 aborting. Other scripts called from job scripts should therefore abort with
 standard non-zero exit status on error, to trigger the job script error trap.