Deprecate running on macOS 12 (and 13, for arm64) (#21569)

This PR sets up infrastructure for deprecating running Pants on macOS
versions, as they go out of support, and uses it to deprecate:

- macOS 12 (x86-64, and arm64)
- macOS 13 (arm64)

Thus, after this PR, Pants supports running on macOS 13 or newer on
x86-64, and macOS 14 or newer on arm64. (Why different? Github provides
macOS 14 arm64 runners, but not macOS 13.)

The infrastructure is general (rather than specific like #21326),
anticipating deprecating one macOS version a year. For instance, we'll
need to deprecate support for macOS 13 (on x86-64) as it approaches
end-of-life in the middle of 2025. From
https://en.wikipedia.org/wiki/MacOS#Timeline_of_releases, it seems like
Apple supports operating systems for about 3 years, e.g. GA macOS 12 was
released October 2021, and the final release was July 2024.

The new `[GLOBAL].allow_deprecated_macos_versions` option is an
allow-list of versions that are permitted, rather than a plain boolean,
to ensure new deprecations are still visible. For instance, I think that
someone who's opted-in to running on macOS 12
(`allow_deprecated_macos_versions = ["12"]`) should still get new alerts
when they upgrade Pants to a version where macOS 13 is deprecated, when
running on macOS 13, and similarly if they run on macOS 11 without
realising it.

## Broader discussion/macOS platform support

Pants currently explicitly supports running on versions of macOS that
are not maintained, and is built on such systems (e.g. we have a
self-hosted arm64 runner with macOS 11). macOS 12 recently reached
end-of-life, and Github is phasing out its (free) hosted runners in
December 2024
(https://github.blog/changelog/2024-08-19-notice-of-upcoming-deprecations-and-breaking-changes-in-github-actions-runners/,
#21333).

There's a desire to reduce Pantsbuild's costs, since it's now volunteer
driven project, so using free runners is much better than relying on
self-hosted ones (both direct money costs to pay for the machines, and
volunteer time to maintain the machines).

To achieve this, we'll need to stick closer to what Github supports,
which seems to be close to what Apple supports. Thus, by deprecating
macOS 12 in Pants 2.24.x, we can limit ourselves to macOS 13+ in 2.25+,
and reduce how long we need to keep macOS 12 machines around. (That is,
as soon as we close off the 2.24.x release series, we can jettison any
macOS 12 machines.)

That is, under the process being implied here, we'll end up with
something like for macOS version support:

| Pants series     | x86-64, not deprecated | x86-64, supported-but-deprecated | arm64, not deprecated | arm64, supported-but-deprecated |
|------------------|------------------------|----------------------------------|-----------------------|---------------------------------|
| 2.22.x           | macOS 10.15            | -                                | macOS 11              | -                               |
| 2.23.x (#21326)  | 12                     | 10.15, 11                        | 12                    | 11                              |
| 2.24.x (this PR) | 13                     | 12                               | 14                    | 12, 13                          |
| 2.25.x           | 13                     | -                                | 14                    | -                               |
| ...              |                        |                                  |                       |                                 |
| 2.A.x (mid 2025) | 14                     | 13                               | 14                    | -                               |
| 2.(A+1).x        | 14                     | -                                | 14                    | -                               |
| ...              |                        |                                  |                       |                                 |
| 2.B.x (mid 2026) | 15                     | 14                               | 15                    | 14                              |
| 2.(B+1).x        | 15                     | -                                | 15                    | -                               |


Note: this may be too annoying for our users: it's a pain if a build
tool has restrictive system support. I note that, for example, Rust
supports 10.15+ (x86-64) and 11.0+ (arm64):
https://doc.rust-lang.org/nightly/rustc/platform-support/apple-darwin.html


Fixes #21333

docs/notes/2.24.x.md

@@ -17,7 +17,7 @@ We offer [formal sponsorship tiers for companies](https://www.pantsbuild.org/spo
 ### Deprecations
 
 - **Python 2.7**: As announced in the v2.23.x release series, Pants v2.24 and later are not proactively tested in CI with Python 2.7 since [Python 2.7 is no longer supported by its maintainers as of 1 January 2020](https://www.python.org/doc/sunset-python-2/). While Pants may continue to work with Python 2.7 in the near term, Pants no longer officially supports use of Python 2.7, and, consequently, any remaining support for Python 2.7 may "bit rot" and diverge over time. Contributions to fix issues with Python 2.7 support will continue to be accepted, but will depend on any community contributions and will not constitute continued official support for Python 2.7.
-- **macOS verisons**: as announced in the v2.23.x release series, Pants v2.24 is built on macOS 12 and so may not work on versions of macOS 10.15 and 11 (which Apple no longer supports).
+- **macOS versions**: Pants v2.24 is the last version that will support macOS 12, as macOS 12 is reaching the end of Apple's support. Future versions of Pants will require macOS 14 or newer (on arm64), and macOS 13 or newer (on x86-64). In addition, as announced in the v2.23.x release series, Pants v2.24 is built on macOS 12 and so may not work on versions of macOS 10.15 and 11 (which Apple no longer supports).
 
 
 ### General

pants.toml

@@ -88,7 +88,7 @@ cache_content_behavior = "fetch"
 
 # Our current macOS 10.15 and 11 infrastructure is working okay, so for now (i.e. 2.24 dev
 # releases), we'll just keep building on them:
-allow_deprecated_macos_before_12 = true
+allow_deprecated_macos_versions = ["10", "11"]
 
 [DEFAULT]
 # Tell `scie-pants` to use our `./pants` bootstrap script.

src/python/pants/bin/pants_runner.py

@@ -20,7 +20,7 @@
 from pants.option.option_value_container import OptionValueContainer
 from pants.option.options_bootstrapper import OptionsBootstrapper
 from pants.util.docutil import doc_url
-from pants.util.osutil import is_macos_before_12
+from pants.util.osutil import get_normalized_arch_name, is_macos_before_12, macos_major_version
 from pants.util.strutil import softwrap
 
 logger = logging.getLogger(__name__)
@@ -124,25 +124,7 @@ def run(self, start_time: float) -> ExitCode:
                         ),
                     )
 
-            if (
-                not global_bootstrap_options.allow_deprecated_macos_before_12
-                and is_macos_before_12()
-            ):
-                warn_or_error(
-                    "2.24.0.dev0",
-                    "using Pants on macOS 10.15 - 11",
-                    softwrap(
-                        f"""
-                        Future versions of Pants will only run on macOS 12 and newer, but this machine
-                        appears older ({platform.platform()}).
-
-                        You can temporarily silence this warning with the
-                        `[GLOBAL].allow_deprecated_macos_before_12` option. If you have questions or
-                        concerns about this, please reach out to us at
-                        {doc_url("community/getting-help")}.
-                        """
-                    ),
-                )
+            _validate_macos_version(global_bootstrap_options)
 
             # N.B. We inline imports to speed up the python thin client run, and avoids importing
             # engine types until after the runner has had a chance to set __PANTS_BIN_NAME.
@@ -167,3 +149,67 @@ def run(self, start_time: float) -> ExitCode:
                 options_bootstrapper=options_bootstrapper,
             )
             return runner.run(start_time)
+
+
+# for each architecture, indicate the first Pants version that doesn't support the given version of
+# macOS, if it is (soon to be) unsupported:
+_MACOS_VERSION_BECOMES_UNSUPPORTED_IN = {
+    # macos-14 is currently oldest github hosted runner for arm
+    "arm64": {
+        10: "2.24.0.dev0",
+        11: "2.24.0.dev0",
+        12: "2.25.0.dev0",
+        13: "2.25.0.dev0",
+        # adding new values here should update the phrasing of the message below
+    },
+    # macos-13 will soon be the oldest (and only) github hosted runner for x86-64 (see https://github.com/pantsbuild/pants/issues/21333)
+    "x86_64": {
+        10: "2.24.0.dev0",
+        11: "2.24.0.dev0",
+        12: "2.25.0.dev0",
+        # adding new values here should update the phrasing of the message below
+    },
+}
+
+
+def _validate_macos_version(global_bootstrap_options: OptionValueContainer) -> None:
+    """Check for running on deprecated/unsupported versions of macOS, and similar."""
+
+    macos_version = macos_major_version()
+    if macos_version is None:
+        # Not macOS, no validation/deprecations required!
+        return
+
+    if global_bootstrap_options.allow_deprecated_macos_before_12 and is_macos_before_12():
+        # If someone has set this (deprecated) option, and the system is older than macOS 12,
+        # they'll don't want messages, so just skip.
+        return
+
+    arch_versions = _MACOS_VERSION_BECOMES_UNSUPPORTED_IN[get_normalized_arch_name()]
+    unsupported_version = arch_versions.get(macos_version)
+
+    is_permitted_deprecated_macos_version = (
+        str(macos_version) in global_bootstrap_options.allow_deprecated_macos_versions
+    )
+
+    if unsupported_version is not None and not is_permitted_deprecated_macos_version:
+        warn_or_error(
+            unsupported_version,
+            "using Pants on older macOS",
+            softwrap(
+                f"""
+                Recent versions of Pants only support macOS 13 and newer (on x86-64) and macOS
+                14 and newer (on arm64), but this machine appears older ({platform.platform()}
+                implies macOS version {macos_version}). This version also isn't permitted by your
+                `[GLOBAL].allow_deprecated_macos_versions` configuration
+                ({global_bootstrap_options.allow_deprecated_macos_versions}).
+
+                Either upgrade your operating system(s), or silence this message (and thus opt-in to
+                potential breakage) by adding "{macos_version}" to the
+                `[GLOBAL].allow_deprecated_macos_versions` list.
+
+                If you have questions or concerns about this, please reach out to us at
+                {doc_url("community/getting-help")}.
+                """
+            ),
+        )

src/python/pants/option/global_options.py

@@ -1801,6 +1801,22 @@ def file_downloads_max_attempts(self) -> int:
             Silence warnings about running Pants on macOS 10.15 - 11. In future versions, Pants will
             only be supported on macOS 12 and newer.
 
+            If you have questions or concerns about this, please reach out to us at
+            {doc_url("community/getting-help")}.
+            """
+        ),
+        removal_version="2.26.0.dev0",
+        removal_hint='Upgrade your operating system or write `allow_deprecated_macos_versions = ["10", "11"]` instead.',
+    )
+
+    allow_deprecated_macos_versions = StrListOption(
+        default=[],
+        advanced=True,
+        help=softwrap(
+            f"""
+            Silence warnings/errors about running Pants on these versions of macOS. Pants only supports
+            recent versions of macOS. You can try running on older versions, but it may or may not work.
+
             If you have questions or concerns about this, please reach out to us at
             {doc_url("community/getting-help")}.
             """

src/python/pants/util/osutil.py

@@ -96,7 +96,7 @@ def get_normalized_arch_name() -> str:
     return normalize_arch_name(get_arch_name())
 
 
-def _macos_major_version() -> None | int:
+def macos_major_version() -> None | int:
     if not hasattr(platform, "mac_ver"):
         return None
 
@@ -108,12 +108,12 @@ def _macos_major_version() -> None | int:
 
 
 def is_macos_big_sur() -> bool:
-    return _macos_major_version() == 11
+    return macos_major_version() == 11
 
 
 def is_macos_before_12() -> bool:
     """MacOS 11 support ended Sep 2023."""
-    version = _macos_major_version()
+    version = macos_major_version()
     return version is not None and version < 12