Announce when deprecated config settings will be removed

cylc/flow/cfgspec/workflow.py

@@ -2123,84 +2123,111 @@ def upg(
     u = upgrader(cfg, descr, broadcast=bool(broadcast))
 
     u.obsolete(
-        '7.8.0', ['runtime', '__MANY__', 'suite state polling', 'template']
+        '7.8.0', ['runtime', '__MANY__', 'suite state polling', 'template'],
+        remove_at='8.9'
     )
-    u.obsolete('7.8.1', ['cylc', 'events', 'reset timer'])
-    u.obsolete('7.8.1', ['cylc', 'events', 'reset inactivity timer'])
-    u.obsolete('8.0.0', ['cylc', 'force run mode'])
-    u.obsolete('7.8.1', ['runtime', '__MANY__', 'events', 'reset timer'])
-    u.obsolete('8.0.0', ['cylc', 'authentication'], is_section=True)
-    u.obsolete('8.0.0', ['cylc', 'include at start-up'])
-    u.obsolete('8.0.0', ['cylc', 'exclude at start-up'])
-    u.obsolete('8.0.0', ['cylc', 'log resolved dependencies'])
-    u.obsolete('8.0.0', ['cylc', 'required run mode'])
+    u.obsolete('7.8.1', ['cylc', 'events', 'reset timer'], remove_at='8.9')
+    u.obsolete('7.8.1', ['cylc', 'events', 'reset inactivity timer'],
+               remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'force run mode'], remove_at='8.9')
+    u.obsolete('7.8.1', ['runtime', '__MANY__', 'events', 'reset timer'],
+               remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'authentication'], is_section=True,
+               remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'include at start-up'], remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'exclude at start-up'], remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'log resolved dependencies'], remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'required run mode'], remove_at='8.9')
     u.obsolete(
         '8.0.0',
-        ['cylc', 'health check interval'])
-    u.obsolete('8.0.0', ['runtime', '__MANY__', 'events', 'mail retry delays'])
-    u.obsolete('8.0.0', ['runtime', '__MANY__', 'extra log files'])
-    u.obsolete('8.0.0', ['runtime', '__MANY__', 'job', 'shell'])
+        ['cylc', 'health check interval'],
+        remove_at='8.9')
+    u.obsolete('8.0.0', ['runtime', '__MANY__', 'events', 'mail retry delays'],
+               remove_at='8.9')
+    u.obsolete('8.0.0', ['runtime', '__MANY__', 'extra log files'],
+               remove_at='8.9')
+    u.obsolete('8.0.0', ['runtime', '__MANY__', 'job', 'shell'],
+               remove_at='8.9')
     u.obsolete(
         '8.0.0',
-        ['runtime', '__MANY__', 'remote', 'suite definition directory']
+        ['runtime', '__MANY__', 'remote', 'suite definition directory'],
+        remove_at='8.9'
     )
-    u.obsolete('8.0.0', ['cylc', 'abort if any task fails'])
-    u.obsolete('8.0.0', ['cylc', 'disable automatic shutdown'])
-    u.obsolete('8.0.0', ['cylc', 'environment'], is_section=True)
-    u.obsolete('8.0.0', ['cylc', 'reference test'], is_section=True)
+    u.obsolete('8.0.0', ['cylc', 'abort if any task fails'],
+               remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'disable automatic shutdown'],
+               remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'environment'], is_section=True,
+               remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'reference test'], is_section=True,
+               remove_at='8.9')
     u.obsolete(
         '8.0.0',
-        ['cylc', 'simulation', 'disable suite event handlers'])
-    u.obsolete('8.0.0', ['cylc', 'simulation'], is_section=True)
-    u.obsolete('8.0.0', ['visualization'], is_section=True)
-    u.obsolete('8.0.0', ['scheduling', 'spawn to max active cycle points'])
+        ['cylc', 'simulation', 'disable suite event handlers'],
+        remove_at='8.9')
+    u.obsolete('8.0.0', ['cylc', 'simulation'], is_section=True,
+               remove_at='8.9')
+    u.obsolete('8.0.0', ['visualization'], is_section=True, remove_at='8.9')
+    u.obsolete('8.0.0', ['scheduling', 'spawn to max active cycle points'],
+               remove_at='8.9')
     u.deprecate(
         '8.0.0',
         ['cylc', 'task event mail interval'],
         ['cylc', 'mail', 'task event batch interval'],
+        remove_at='8.9'
     )
     u.deprecate(
         '8.0.0',
         ['runtime', '__MANY__', 'suite state polling'],
         ['runtime', '__MANY__', 'workflow state polling'],
         is_section=True,
+        remove_at='8.9'
     )
     u.obsolete(
-        '8.0.0', ['runtime', '__MANY__', 'workflow state polling', 'host'])
+        '8.0.0', ['runtime', '__MANY__', 'workflow state polling', 'host'],
+        remove_at='8.9'
+    )
     u.obsolete(
-        '8.0.0', ['runtime', '__MANY__', 'workflow state polling', 'user'])
+        '8.0.0', ['runtime', '__MANY__', 'workflow state polling', 'user'],
+        remove_at='8.9'
+    )
 
     u.deprecate(
         '8.3.0',
         ['runtime', '__MANY__', 'workflow state polling', 'run-dir'],
         ['runtime', '__MANY__', 'workflow state polling', 'alt-cylc-run-dir'],
+        remove_at='8.9'
     )
 
     u.deprecate(
         '8.0.0',
         ['cylc', 'parameters'],
         ['task parameters'],
         is_section=True,
+        remove_at='8.9'
     )
     u.deprecate(
         '8.0.0',
         ['cylc', 'parameter templates'],
         ['task parameters', 'templates'],
         is_section=True,
+        remove_at='8.9'
     )
     # Whole workflow task mail settings
     for mail_setting in ['to', 'from', 'footer']:
         u.deprecate(
             '8.0.0',
             ['cylc', 'events', f'mail {mail_setting}'],
             ['cylc', 'mail', mail_setting],
+            remove_at='8.9'
         )
     # Task mail settings in [runtime][TASK]
     for mail_setting in ['to', 'from']:
         u.deprecate(
             '8.0.0',
             ['runtime', '__MANY__', 'events', f'mail {mail_setting}'],
             ['runtime', '__MANY__', 'mail', mail_setting],
+            remove_at='8.9'
         )
     u.deprecate(
         '8.0.0',
@@ -2210,6 +2237,7 @@ def upg(
             'DELETED (OBSOLETE) - use "global.cylc[scheduler][mail]smtp" '
             'instead')
         ),
+        remove_at='8.9'
     )
     u.deprecate(
         '8.0.0',
@@ -2219,20 +2247,23 @@ def upg(
             'DELETED (OBSOLETE) - use "global.cylc[scheduler][mail]smtp" '
             'instead')
         ),
+        remove_at='8.9'
     )
     u.deprecate(
         '8.0.0',
         ['scheduling', 'max active cycle points'],
         ['scheduling', 'runahead limit'],
         cvtr=converter(
             lambda x: f'P{int(x) - 1}' if x != '' else '',
-            '"{old}" -> "{new}"'
+            '"{old}" -> "{new}"',
         ),
+        remove_at='8.9'
     )
     u.deprecate(
         '8.0.0',
         ['scheduling', 'hold after point'],
         ['scheduling', 'hold after cycle point'],
+        remove_at='8.9'
     )
 
     for job_setting in [
@@ -2246,6 +2277,7 @@ def upg(
             '8.0.0',
             ['runtime', '__MANY__', 'job', job_setting],
             ['runtime', '__MANY__', job_setting],
+            remove_at='8.9'
         )
 
     # Workflow timeout is now measured from start of run.
@@ -2266,6 +2298,7 @@ def upg(
             '8.0.0',
             ['cylc', 'events', old],
             ['cylc', 'events', new],
+            remove_at='8.9',
         )
 
     for old in [
@@ -2288,6 +2321,7 @@ def upg(
             '8.0.0',
             ['runtime', '__MANY__', 'events', old],
             ['runtime', '__MANY__', 'events', f"{old}s"],
+            remove_at='8.9',
         )
 
     for old in [
@@ -2298,13 +2332,14 @@ def upg(
         'abort if inactivity handler fails',
         'abort if stalled handler fails',
     ]:
-        u.obsolete('8.0.0', ['cylc', 'events', old])
+        u.obsolete('8.0.0', ['cylc', 'events', old,], remove_at='8.9')
 
     u.deprecate(
         '8.0.0',
         ['cylc'],
         ['scheduler'],
         is_section=True,
+        remove_at='8.9'
     )
     u.upgrade()
 
@@ -2359,7 +2394,8 @@ def upgrade_graph_section(cfg: Dict[str, Any], descr: str) -> None:
                 if keys:
                     msg = (
                         'graph items were automatically upgraded '
-                        f'in "{descr}":\n'
+                        f'in "{descr}" - support for the old item will be '
+                        'removed at Cylc 8.9:\n'
                         f' * (8.0.0) {msg_old} -> {msg_new}'
                     )
                     if list_cp:

cylc/flow/parsec/upgrade.py

@@ -69,7 +69,7 @@ def __init__(self, cfg: dict, descr: str, broadcast: bool = False):
 
     def deprecate(
         self, vn, oldkeys, newkeys=None,
-        cvtr=None, is_section=False,
+        cvtr=None, is_section=False, remove_at=None
     ):
         """Replace a deprecated key from a config
         Args:
@@ -84,6 +84,8 @@ def deprecate(
                 description of that function.
             is_section (bool):
                 Is a section heading.
+            remove_at (str):
+                Cylc version when this upgrader will be removed
         """
         if vn not in self.upgrades:
             self.upgrades[vn] = []
@@ -92,10 +94,10 @@ def deprecate(
         self.upgrades[vn].append(
             {
                 'old': oldkeys, 'new': newkeys, 'cvt': cvtr,
-                'is_section': is_section
+                'is_section': is_section, 'remove_at': remove_at
             })
 
-    def obsolete(self, vn, oldkeys, is_section=False):
+    def obsolete(self, vn, oldkeys, is_section=False, remove_at=None):
         """Remove an obsolete key from a config
         Args:
             vn (str):
@@ -104,14 +106,16 @@ def obsolete(self, vn, oldkeys, is_section=False):
                 Path within config to be removed.
             is_section (bool):
                 Is a section heading.
+            remove_at (str):
+                Cylc version when this obsoletion will become an error
         """
         if vn not in self.upgrades:
             self.upgrades[vn] = []
         cvtr = converter(lambda x: x, "DELETED (OBSOLETE)")  # identity
         self.upgrades[vn].append(
             {
                 'old': oldkeys, 'new': None, 'cvt': cvtr,
-                'is_section': is_section
+                'is_section': is_section, 'remove_at': remove_at
             })
 
     def get_item(self, keys):
@@ -183,6 +187,7 @@ def expand(self, upg):
                         'new': None,
                         'cvt': upg['cvt'],
                         'is_section': upg['is_section'],
+                        'remove_at': upg.get('remove_at')
                     })
                 return exp_upgs
             npre = []
@@ -200,6 +205,7 @@ def expand(self, upg):
                     'new': npre + [m] + npost,
                     'cvt': upg['cvt'],
                     'is_section': upg['is_section'],
+                    'remove_at': upg.get('remove_at')
                 })
         return exp_upgs
 
@@ -232,6 +238,13 @@ def upgrade(self):
                             old=old,
                             new=upg['cvt'].convert(old)
                         )
+                        if (remove_at := upg.get('remove_at')) is not None:
+                            if upg['new']:
+                                msg += (f' - support for the old item will be '
+                                        f'removed at Cylc {remove_at}')
+                            else:
+                                msg += (f' - this will fail validation in '
+                                        f'Cylc {remove_at}')
                         warnings.setdefault(vn, [])
                         warnings[vn].append(msg)
                         self.del_item(upg['old'])