response to review

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,22 +83,100 @@ 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::
 
    Cylc 9 will no longer automatically upgrade obselete Cylc 7
    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.**

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
 ------------