728: simplify platforms section

Author: oliver-sanders

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

@@ -6,46 +6,11 @@ Platforms
 .. admonition:: Does This Change Affect Me?
    :class: tip
 
-   .. cylc-scope:: flow.cylc
+   Cylc platforms are a new feature which replace the task ``job`` and
+   ``remote`` configuration sections:
 
-   Platforms replace the deprecated :cylc:conf:`[runtime][<namespace>][job]`
-   and :cylc:conf:`[runtime][<namespace>][remote]`
-   sections:
-
-   .. code-block:: cylc
-
-      [runtime]
-          [[foo]]
-              [[[job]]]
-                  batch system = slurm
-              [[[remote]]]
-                  host = my_supercomputer
-
-   .. cylc-scope::
-
-   Read this section if your workflow's jobs run on a remote computer or if
-   you see the following warning on running ``cylc validate``:
-
-   .. code-block:: console
-
-      WARNING - deprecated settings found (please replace with [runtime][foo]platform):
-          [runtime][foo][remote]host
-          [runtime][foo][job]batch system
-
-   If you currently use the ``rose host-select`` utility or a similar host
-   selection or load balancing utility the intelligent host selection
-   functionality of Cylc 8 may be used instead:
-
-   .. code-block:: cylc
-
-      [runtime]
-          [[task1]]
-              [[[remote]]]
-                  host = $(rose host-select my-computer)
-          [[task2]]
-              # An example of a home-rolled host selector
-              [[[remote]]]
-                  host = $(test $((RANDOM%2)) -eq 0 && echo "host_a" || echo "host_b")
+   * :cylc:conf:`[runtime][<namespace>][job]`
+   * :cylc:conf:`[runtime][<namespace>][remote]`
 
 
 Overview
@@ -57,23 +22,17 @@ Overview
    - The terms :term:`job runner` (in Cylc 8 configurations) and batch system
      (in Cylc 7 configurations) are equivalent.
 
-Cylc 7 defines settings for remote :term:`jobs <job>` in each
-:term:`task's <task>` definition.
-
-Cylc 8 allows site administrators (and users) to configure
-:term:`platforms <platform>` in ``global.cylc``. A platform can have
-multiple hosts with associated platform-specific settings. Users only need to
-select the platform for their task jobs.
+Submitting a job to a :term:`job runner` may require configuration.
 
-Platforms also define how hosts are selected from each platform:
+In Cylc 7 this configuration must be provided for each task in the workflow
+configuration (``suite.rc``).
 
-- Randomly (default)
-- By definition order
+In Cylc 8 "platforms" can be defined in the global configuration
+(:cylc:conf:`global.cylc`) so that this configuration doesn't have to be
+repeated for each task in each workflow.
 
-There may be cases where sets of platforms (for example a group of
-standalone compute servers, or a pair of mirrored HPC's) might be equally
-suitable for a task, but not share files systems to allow them to constitute
-a single platform. Such platforms can be set up to be ``platform groups``
+Cylc "platforms" may configure hostnames, job runners and more. Only the
+platform name needs to be specified in the task configuration.
 
 .. seealso::
 
@@ -92,6 +51,20 @@ a single platform. Such platforms can be set up to be ``platform groups``
    Deprecated settings will be removed in a later release of Cylc.
 
 
+What is a Platform?
+-------------------
+
+A "platform" represents one or more hosts from which jobs can be submitted to or
+polled from a common job submission system.
+
+If a platform has multiple hosts Cylc will automatically select a host when
+needed and will fallback to other hosts if it is not contactable.
+
+A "platform group" represents a collection of independent platforms. Cylc will
+automatically select a platform and will fallback to other platforms in the
+group (for appropriate operations) if the platform is not contactable.
+
+
 Examples
 --------