Improve back-compat info. (#407)

* Fix typos in caveats page.

* Improve back-compat info.

* Update src/7-to-8/caveats.rst

Co-authored-by: Oliver Sanders <[email protected]>

* 728: add "Does This Change Affect Me" box

Co-authored-by: Oliver Sanders <[email protected]>

Author: hjoliver

src/7-to-8/caveats.rst

@@ -1,8 +1,8 @@
 Cylc |version| Caveats
 ======================
 
-This is a beta release of Cylc. There are some loose ends and features which
-have not yet been (re)implemented.
+This is a Cylc pre-release. There are some features which
+have not yet been implemented.
 
 
 Cylc Flow
@@ -58,7 +58,7 @@ Multiple Selection
 
    * https://github.com/cylc/cylc-ui/issues/434
 Installing Workflows
-   At present there is no way to view or install non-installed workflows (a.k.a.
+   At present there is no way to view or install
    :term:`source workflows <source directory>`) in the UI.
 Rose Edit
    Rose Edit is awaiting reimplementation in the UI.
@@ -107,7 +107,7 @@ Authorization
    A full-featured authorization system has been implemented for Cylc 8, but
    the UI doesn't yet provide easy access to other users' UI Servers.
 
-CLI Via UIS
+CLI via UIS
    The ability to route Cylc commands via the UIS is planned for a future release
 
    * https://github.com/cylc/cylc-flow/issues/3528

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

@@ -1,3 +1,5 @@
+.. _MajorChangesCLI:
+
 Command Line Interface
 ======================
 

src/7-to-8/major-changes/excluding-tasks.rst

@@ -0,0 +1,43 @@
+.. _MajorChangesExcludingTasksAtStartup:
+
+Excluding Tasks at Start-up is Not Supported
+============================================
+
+.. admonition:: Does This Change Affect Me?
+   :class: tip
+
+   This will affect you if your workflows use the following configurations:
+
+   * ``[scheduling][special tasks]include at start-up``
+   * ``[scheduling][special tasks]exclude at start-up``
+
+
+Overview
+--------
+
+The Cylc 7 sheduler allowed you to exclude tasks from the scheduler at start-up: 
+
+.. code-block:: cylc
+
+   # Cylc 7 only 
+   [scheduling]
+      [[special tasks]]
+           include at start-up = foo, bar, baz  # Cylc 8 ERROR!
+           exclude at start-up = bar  # Cylc 8 ERROR!
+
+The first config item above excludes all task names not in the include-list;
+the second excludes specific tasks that would otherwise be included.
+
+The Cylc 7 scheduler started up with an instance of every task in its "task
+pool", and the workflow evolved by each task spawning its own next-cycle
+instance at the right time. So, if you excluded a task a start-up it would not
+run in the workflow at all unless manually inserted later at runtime.
+
+The Cylc 8 scheduler starts up with only the initial tasks in the graph and the 
+workflow evolves by spawning new tasks on demand as dictated by the graph.
+Consequently excluding a task at start up as described above would have no
+effect at all on most tasks.
+
+This feature also predated the current Cylc dependency graph configuration. To
+exclude tasks now without entirely removing them from the workflow definition,
+just comment them out of the graph.

src/7-to-8/summary.rst

@@ -25,13 +25,29 @@ The workflow configuration file has changed from ``suite.rc`` to ``flow.cylc``.
 Cylc 7 Compatibility Mode
 -------------------------
 
-Cylc 8 can run Cylc 7 workflows out of the box.
+The old ``suite.rc`` filename triggers a :ref:`backward
+compatibility mode<cylc_7_compat_mode>` in Cylc 8 which supports Cylc 7
+workflow configruations out of the box, with the following caveats:
 
-Run ``cylc validate`` on your ``suite.rc`` (using Cylc 7) to check it does
-not contain any deprecated syntax before attempting to run it with Cylc 8.
+.. warning::
+
+   Cylc 6 syntax deprecated by Cylc 7 is now obsolete. Run ``cylc validate``
+   *with Cylc 7* on your ``suite.rc`` to check for deprecation warnings and fix
+   those before validating with Cylc 8.
+
+.. warning::
 
-The old ``suite.rc`` filename triggers a backward compatibility mode,
-for more information see :ref:`cylc_7_compat_mode`.
+   Check for any use of Cylc commands in task scripting. Some Cylc 7 commands
+   have been removed and some others now behave differently.
+   See :ref:`command line interface changes<MajorChangesCLI>`.
+
+.. warning::
+
+   Cylc 8 does not support
+   :ref:`excluding tasks at start-up<MajorChangesExcludingTasksAtStartup>`.
+   If your workflow used this old functionality, it may have been used in
+   combination with the ``cylc insert`` command (which has been removed from
+   Cylc 8) and ``cylc remove`` (which still exists but is much less needed).
 
 .. warning::
 
@@ -64,7 +80,6 @@ Architecture
 
    - Technical Reference: :ref:`architecture-reference`
 
-
 The main Cylc 8 system components are:
 
 - **Cylc Scheduler**
@@ -335,8 +350,11 @@ Cylc Install
 
 Cylc install cleanly separates workflow source directory from run directory,
 and installs workflow files into the run directory at start-up.
+
 - ``cylc install`` copies workflow source files to a dedicated run-directory
+
 - :term:`source directory` locations can be set in global config
+
 - each install creates a new numbered :term:`run directory` (by default)
 
 .. code-block:: console