Deprecate using scie-pants older than 0.12.2, improve upgrade docs (C…

…herry-pick of #21726) (#21731)

This makes two changes:

- upgrades the "upgrading pants" docs call out into a dedicated/linkable
section, and calls out that the package manager can be used to upgrade
too
- institutes an deprecation warning when running with scie-pants older
than 0.12.2

This'll be cherrypicked to 2.24 to get ahead of the upgrade experience
of going from 2.24 to 2.25.

Fixes #21603

Co-authored-by: Huon Wilson <[email protected]>

docs/docs/getting-started/installing-pants.mdx

@@ -35,16 +35,14 @@ bin i github.com/pantsbuild/scie-pants ~/.local/bin/pants
 
 If you have difficulty installing Pants, see our [getting help](/community/getting-help) for community resources to help you resolve your issue.
 
-:::tip Upgrading Pants
+## Upgrading Pants
+
 The `pants` launcher binary will automatically install and use the Pants version specified in `pants.toml`, so upgrading Pants in a repo is as simple as editing `pants_version` in that file.
 
-To upgrade the `pants` launcher binary itself, run
+To upgrade the `pants` launcher binary itself, either:
 
-```
-SCIE_BOOT=update pants
-```
-
-:::
+- Use the package manager you used to install Pants. For example, with Homebrew: `brew update && brew upgrade pantsbuild/tap/pants`.
+- Use its built-in self-update functionality: `SCIE_BOOT=update pants`.
 
 ## Running Pants from sources
 

docs/notes/2.24.x.md

@@ -22,6 +22,7 @@ Thank you to [Klayvio](https://www.klaviyo.com/) and [Normal Computing](https://
 
 - **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 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).
+- **Pants runner**: Pants v2.24 is the last version that supports versions of the `pants` launcher binary older than 0.12.2. Pants v2.25 and newer will require 0.12.2. [Follow the upgrade instructions](https://www.pantsbuild.org/2.24/docs/getting-started/installing-pants#upgrading-pants).
 
 
 ### General

src/python/pants/bin/pants_runner.py

@@ -25,8 +25,9 @@
 
 logger = logging.getLogger(__name__)
 
-# Pants 2.18 is using a new distribution model, that's supported (sans bugs) in 0.10.0.
-MINIMUM_SCIE_PANTS_VERSION = Version("0.10.0")
+# First version with working Python 3.11 support:
+# https://github.com/pantsbuild/scie-pants/releases/tag/v0.12.2
+MINIMUM_SCIE_PANTS_VERSION = Version("0.12.2")
 
 
 @dataclass(frozen=True)
@@ -115,11 +116,11 @@ def run(self, start_time: float) -> ExitCode:
                         else "Run `PANTS_BOOTSTRAP_VERSION=report pants` to see the current version of the `pants` launcher binary"
                     )
                     warn_or_error(
-                        "2.18.0.dev6",
+                        "2.25.0.dev0",
                         f"using a `pants` launcher binary older than {MINIMUM_SCIE_PANTS_VERSION}",
                         softwrap(
                             f"""
-                            {current_version_text}, and see {doc_url("docs/getting-started/installing-pants")} for how to upgrade.
+                            {current_version_text}, and see {doc_url("docs/getting-started/installing-pants#upgrading-pants")} for how to upgrade.
                             """
                         ),
                     )