From e92b49acf6746db274f6ee8819fbb485adeb7b80 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Wed, 25 Aug 2021 15:39:17 +0100
Subject: [PATCH] response to review

---
 src/7-to-8/major-changes/before-you-start.rst | 97 +++++++++++++++++--
 src/7-to-8/summary.rst                        |  2 +
 2 files changed, 90 insertions(+), 9 deletions(-)

diff --git a/src/7-to-8/major-changes/before-you-start.rst b/src/7-to-8/major-changes/before-you-start.rst
index ca90984105..593354b073 100644
--- a/src/7-to-8/major-changes/before-you-start.rst
+++ b/src/7-to-8/major-changes/before-you-start.rst
@@ -41,10 +41,9 @@ Consider this configuration:
 
    [scheduling]
        initial cycle point = 11000101T00
-
-   [[dependencies]]
-       [[[R1]]]
-           graph = task
+       [[dependencies]]
+           [[[R1]]]
+               graph = task
 
    [runtime]
        [[task]]
@@ -74,6 +73,8 @@ validation.
           R1
    IllegalItemError: [runtime][task]pre-command scripting
 
+Fixing Validation Failure
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You must change the configuration yourself:
 
@@ -82,18 +83,28 @@ You must change the configuration yourself:
    -     pre-command scripting = echo "Hello World"
    +     pre-script = echo "Hello World"
 
-Validation will now succed.
+Validation will now succeed.
 
 This will leave you with just the warning about the changes to the graph
 format: You might wish to fix this now:
 
-.. code-block:: diff
+Fixing Deprecation Warning
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-   [[dependencies]]
-       [[[R1]]]
-           graph = task
+For the example given Cylc 8 will validate without warning after making the
+following changes. (explanation of
+:ref:`changes to graph section. <7-to-8.summary.graph_syntax>`
+):
 
+.. code-block:: diff
 
+   [scheduling]
+       initial cycle point = 11000101T00
+   -   [[dependencies]]
+   +   [[graph]]
+   -       [[[R1]]]
+   -           graph = task
+   +       R1 = task
 
 .. warning::
 
@@ -101,3 +112,71 @@ format: You might wish to fix this now:
    configurations. It's a good idea to try and remove the configuration items
    causing to these warnings as part of routine workflow review and
    maintenance to avoid problems when a major Cylc version is released.
+
+Host to platform upgrade logic
+------------------------------
+
+.. seealso::
+
+   :ref:`Details of how platforms work.<MajorChangesPlatforms>`
+
+   .. TODO reference to how to write platforms page
+
+If you have a Cylc 7 workflow where tasks submit jobs to remote hosts
+Cylc 8 will attempt to find a platform which matches the task specfication.
+
+.. important::
+
+   Cylc 8 needs platforms matching the Cylc 7 job configuration to be
+   available in :cylc:conf:`global.cylc[platforms]`.
+
+Example
+^^^^^^^
+
+.. note::
+
+   In the following example ``job runner`` in **Cylc 8** configurations
+   and ``batch system`` in **Cylc 7** configurations refer to the same item.
+
+If, for example you had a **Cylc 8** ``global.cylc`` with the following
+platforms section:
+
+.. code-block:: cylc
+   :caption: Part of a Cylc global configuration
+
+   [platforms]
+       [[supercomputer_A]]
+           hosts = localhost
+           job runner = slurm
+       [[supercomputer_B]]
+           hosts = tigger, wol, eyore
+           batch system = pbs
+
+And you have a **cylc 7** workflow runtime configuration:
+
+.. code-block:: cylc
+   :caption: Part of ``suite.rc`` or ``flow.cylc``
+
+   [runtime]
+       [[task1]]
+           [[[job]]]
+               batch system = slurm
+       [[task2]]
+           [[[remote]]]
+               hosts = eyore
+           [[[job]]]
+               batch system = pbs
+
+
+Then, ``task1`` will be assigned platform
+``supercomputer_A`` because the host
+specified is in the list of hosts **and** the batch system is the same and task
+``task2`` will run on ``supercomputer_B``.
+
+.. important::
+
+   for simplicity, and becuause the ``host`` key is a special case (it can
+   match and host in ``[platform]hosts``) we only show these two config keys
+   here. In reality, **Cylc 8 compares the whole of**
+   ``[<task>][job]`` **and** ``[<task>][remote]``
+   **sections and all items must match to select a platform.**
diff --git a/src/7-to-8/summary.rst b/src/7-to-8/summary.rst
index 5a77f2065b..b7e78515f5 100644
--- a/src/7-to-8/summary.rst
+++ b/src/7-to-8/summary.rst
@@ -178,6 +178,8 @@ on the same platform to interact with task jobs.
    These deprecated settings will be removed at Cylc 9.
 
 
+.. _7-to-8.summary.graph_syntax:
+
 Graph Syntax
 ------------