SCons · mwichmann · Jul 9, 2026
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -131,6 +131,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - zip tool now uses zipfile module's "from_file" method to populate
       ZipInfo records, rather than doing manually.
     - Some cleanups in Subst.py. Functionality does not change.
+    - Deprecate the legacy job scheduler and feature flag. The feature flag
+      is renamed to "legacy_sched_deprecated".
     - Reference manual improvements:
       * More clarifications in Builder Methods section.
       * Clarify VariantDir behavior when switching from duplicate=True (the

diff --git a/RELEASE.txt b/RELEASE.txt
@@ -28,6 +28,13 @@ DEPRECATED FUNCTIONALITY
 - Deprecated using signature-file-per-directory (aka old-style SConsign)
   via the SConsignFile(name=None) call.
 
+- The legacy job scheduler, which was superseded by a new scheduler in
+  SCons 4.7  but remained available as a fallback, is deprecated and
+  will be removed in the next release. The --experimental feature flag
+  to select the legacy scheduler is renamed to "legacy_sched_deprecated"
+  to give a clear indication of the status change; the flag will also
+  be removed in the next release.
+
 REMOVED FUNCTIONALITY
 ---------------------
 

diff --git a/SCons/Script/SConsOptions.py b/SCons/Script/SConsOptions.py
@@ -42,7 +42,8 @@
 
 diskcheck_all = SCons.Node.FS.diskcheck_types()
 
-experimental_features = {'warp_speed', 'transporter', 'ninja', 'legacy_sched'}
+# legacy_sched renamed legacy_sched_deprecated in 4.11, scheduled for removal
+experimental_features = {'warp_speed', 'transporter', 'ninja', 'legacy_sched_deprecated'}
 
 
 def diskcheck_convert(value):

diff --git a/SCons/Taskmaster/Job.py b/SCons/Taskmaster/Job.py
@@ -72,12 +72,15 @@ class Jobs:
     """
 
     def __init__(self, num, taskmaster) -> None:
-        """
-        Create 'num' jobs using the given taskmaster. The exact implementation
-        used varies with the number of jobs requested and the state of the `legacy_sched` flag
-        to `--experimental`.
-        """
+        """Create *num* jobs using the given taskmaster.
 
+        The exact implementation used varies with the number of jobs
+        requested and the scheduler selected - the old scheduler is
+        available through CLI ``--experimental=legacy_sched_deprecated``.
+
+        .. versionchanged: NEXT_RELEASE
+           Legacy scheduler deprecated, flag renamed to ``legacy_sched_deprecated``
+        """
         # Importing GetOption here instead of at top of file to avoid
         # circular imports
         # pylint: disable=import-outside-toplevel
@@ -88,7 +91,7 @@ def __init__(self, num, taskmaster) -> None:
             stack_size = default_stack_size
 
         experimental_option = GetOption('experimental') or []
-        if 'legacy_sched' in experimental_option:
+        if 'legacy_sched_deprecated' in experimental_option:
             if num > 1:
                 self.job = LegacyParallel(taskmaster, num, stack_size)
             else:

diff --git a/SCons/Taskmaster/JobTests.py b/SCons/Taskmaster/JobTests.py
@@ -313,7 +313,7 @@ def get(self):
 
         try:
             taskmaster = Taskmaster(3, self, SleepTask)
-            OptionsParser.values.experimental.append('legacy_sched')
+            OptionsParser.values.experimental.append('legacy_sched_deprecated')
             jobs = SCons.Taskmaster.Job.Jobs(2, taskmaster)
             OptionsParser.values.experimental.pop()
             jobs.run()
@@ -529,7 +529,7 @@ def runTest(self) -> None:
         self._test_seq(1)
 
         # Now run test with LegacyParallel
-        OptionsParser.values.experimental=['legacy_sched']
+        OptionsParser.values.experimental=['legacy_sched_deprecated']
         self._test_seq(1)
 
 class ParallelTaskTest(_SConsTaskTest):
@@ -538,7 +538,7 @@ def runTest(self) -> None:
         self._test_seq(num_jobs)
 
         # Now run test with LegacyParallel
-        OptionsParser.values.experimental=['legacy_sched']
+        OptionsParser.values.experimental=['legacy_sched_deprecated']
         self._test_seq(num_jobs)
 
 

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
@@ -1258,14 +1258,33 @@ the mechanisms in the specified order.</para>
         the special tokens <literal>all</literal> or <literal>none</literal>.
         A comma-separated string can be used to select multiple features.
         The default setting is <literal>none</literal>.</para>
-      <para>Current available features are:
-        <literal>ninja</literal> (<emphasis>New in version 4.2</emphasis>),
-        <literal>legacy_sched</literal> (<emphasis>New in version 4.6.0</emphasis>).
+
+      <para>Current available features are
+        <literal>ninja</literal> (<emphasis>new in version 4.2</emphasis>)
+        and
+        <literal>legacy_sched_deprecated</literal>
+        (<emphasis>new in, and deprecated since, version NEXT_RELEASE</emphasis>).
       </para>
+      <note>
+      <para>
+        The legacy scheduler is not strictly an experimental feature.
+        The feature flag selects the job scheduler which was
+        the &SCons; default prior to version 4.7.
+        The feature flag was introduced as <literal>legacy_sched</literal>
+        in version 4.7.
+        The legacy scheduler is due to be removed in a future release,
+        so the feature flag is now deprecated. In version NEXT_RELEASE,
+        it was renamed to <literal>legacy_sched_deprecated</literal>,
+        so that existing users will receive a signal - due to the nature
+        of experimental feature flags it is not possible to use the
+        standard &SCons; deprecation warning mechanism here.
+      </para></note>
       <caution><para>
-        No Support offered for any features or tools enabled by this flag.
+        Experimental features come with no compatibility promises -
+        a given feature could change significantly in a future release,
+        or disappear completely.
       </para></caution>
-      <para><emphasis>New in version 4.2 (experimental).</emphasis></para>
+      <para><emphasis>Option added in version 4.2.</emphasis></para>
     </listitem>
   </varlistentry>
 

diff --git a/test/Interactive/taskmastertrace.py b/test/Interactive/taskmastertrace.py
@@ -46,7 +46,7 @@
 test.write('foo.in', "foo.in 1\n")
 
 
-scons = test.start(arguments = '-Q --interactive --experimental=legacy_sched')
+scons = test.start(arguments = '-Q --interactive --experimental=legacy_sched_deprecated')
 
 scons.send("build foo.out 1\n")
 

diff --git a/test/option/option--experimental.py b/test/option/option--experimental.py
@@ -36,13 +36,13 @@
 tests = [
     ('.', []),
     ('--experimental=ninja', ['ninja']),
-    ('--experimental=legacy_sched', ['legacy_sched']),
-    ('--experimental=all', ['legacy_sched', 'ninja', 'transporter', 'warp_speed']),
+    ('--experimental=legacy_sched_deprecated', ['legacy_sched_deprecated']),
+    ('--experimental=all', ['legacy_sched_deprecated', 'ninja', 'transporter', 'warp_speed']),
     ('--experimental=none', []),
 ]
 
 for args, exper in tests:
-    read_string = """All Features=legacy_sched,ninja,transporter,warp_speed
+    read_string = """All Features=legacy_sched_deprecated,ninja,transporter,warp_speed
 Experimental=%s
 """ % (exper)
     test.run(arguments=args,
@@ -51,7 +51,7 @@
 test.run(arguments='--experimental=warp_drive',
          stderr="""usage: scons [OPTIONS] [VARIABLES] [TARGETS]
 
-SCons Error: option --experimental: invalid choice: 'warp_drive' (choose from 'all','none','legacy_sched','ninja','transporter','warp_speed')
+SCons Error: option --experimental: invalid choice: 'warp_drive' (choose from 'all','none','legacy_sched_deprecated','ninja','transporter','warp_speed')
 """,
          status=2)
 

diff --git a/test/option/taskmastertrace.py b/test/option/taskmastertrace.py
@@ -42,7 +42,7 @@
 
 expect_stdout = test.wrap_stdout(test.read('taskmaster_expected_stdout_1.txt', mode='r'))
 
-test.run(arguments='--experimental=legacy_sched --taskmastertrace=- .', stdout=expect_stdout)
+test.run(arguments='--experimental=legacy_sched_deprecated --taskmastertrace=- .', stdout=expect_stdout)
 
 test.run(arguments='-c .')
 
@@ -52,7 +52,7 @@
 """)
 
 # Test LegacyParallel Job implementation
-test.run(arguments='--experimental=legacy_sched --taskmastertrace=trace.out .', stdout=expect_stdout)
+test.run(arguments='--experimental=legacy_sched_deprecated --taskmastertrace=trace.out .', stdout=expect_stdout)
 test.must_match_file('trace.out', 'taskmaster_expected_file_1.txt', mode='r')
 
 # Test NewParallel Job implementation