misc 2.25 release notes copyedits and sorting (Cherry-pick of #21934) (…

…#21940)

Co-authored-by: cburroughs <[email protected]>

docs/notes/2.25.x.md

@@ -18,13 +18,13 @@ Thank you to [Klayvio](https://www.klaviyo.com/) and [Normal Computing](https://
 
 ### General
 
-- Fixed a longstanding bug in the processing of [synthetic targets](https://www.pantsbuild.org/2.24/docs/writing-plugins/the-target-api/concepts#synthetic-targets-api). This fix has the side-effect of requiring immutability and hashability of scalar values in BUILD files, which was always assumed but not enforced. This may cause BUILD file parsing errors, if you have custom field types involving custom mutable data structures. See ([#21725](https://github.com/pantsbuild/pants/pull/21725)) for more.
-- [Fixed](https://github.com/pantsbuild/pants/pull/21665) bug where `pants --export-resolve=<resolve> --export-py-generated-sources-in-resolve=<resolve>` fails (see [#21659](https://github.com/pantsbuild/pants/issues/21659) for more info).
+- Fixed a longstanding bug in the processing of [synthetic targets](https://www.pantsbuild.org/2.25/docs/writing-plugins/the-target-api/concepts#synthetic-targets-api). This fix has the side-effect of requiring immutability and hashability of scalar values in BUILD files, which was always assumed but not enforced. This may cause BUILD file parsing errors, if you have custom field types involving custom mutable data structures. See ([#21725](https://github.com/pantsbuild/pants/pull/21725)) for more.
+- [Fixed](https://github.com/pantsbuild/pants/pull/21665) a bug where `pants --export-resolve=<resolve> --export-py-generated-sources-in-resolve=<resolve>` fails (see [#21659](https://github.com/pantsbuild/pants/issues/21659) for more info).
 - [Fixed](https://github.com/pantsbuild/pants/pull/21694) bug where an `archive` target is unable to produce a ZIP file with no extension (see [#21693](https://github.com/pantsbuild/pants/issues/21693) for more info).
 - `[subprocess-environment].env_vars` and `extra_env_vars` (on many subsystems and targets) now supports a generalised glob syntax using Python [fnmatch](https://docs.python.org/3/library/fnmatch.html) to construct patterns like `AWS_*`, `TF_*`, and `S2TESTS_*`.
 - Suspicious values now generate a warning instead of hard error when using the `<PATH>` special value to inject shell `PATH` values to the `system-binaries` subsystem.
 
-#### Remote Caching/Execution
+### Remote Caching/Execution
 
 Pants now sends a `user-agent` header with every request to a remote store or a remote execution service,
 even when other headers are configured. If necessary, the user may override the user agent by specifying
@@ -44,7 +44,7 @@ The version of Python used by Pants itself has been updated to [3.11](https://do
 - 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`.
 
-That Pants itself happens to be partially writtin in Python has no bearing on the versions of Python that Pants can use to test and build your code.
+Note: The fact that Pants happens to be partially written in Python has no bearing on the versions of Python that Pants can use to test and build your code.
 
 ### Goals
 
@@ -67,10 +67,14 @@ use_rust_parser = false
 Strict adherence to the [schema of Docker registry configuration](https://www.pantsbuild.org/2.25/reference/subsystems/docker#registries) is now required.
 Previously we did ad-hoc coercion of some field values, so that, e.g., you could provide a "true"/"false" string as a boolean value. Now we require actual booleans.
 
-Fixed an error which was caused when the same tool appeaed in both the `--docker-tools` and `--docker-optional-tools` options.
+Fixed an error which was caused when the same tool appeared in both the `--docker-tools` and `--docker-optional-tools` options.
 
 Stages in multi-stage builds which only used a hash to identify the image version (that is, no tag) are now surfaced. They can now be used in the `docker_image.target_state` field.
 
+#### Go
+
+Fix a bug with the setup of the gRPC protobuf plugins where a `go install` invocation was prevented from accessing the Go module proxy during its build of those plugins, which caused those builds to fail.
+
 #### Helm
 
 Strict adherence to the [schema of Helm OCI registry configuration](https://www.pantsbuild.org/2.25/reference/subsystems/helm#registries) is now required.
@@ -86,6 +90,49 @@ The default "globs" for matching yaml in charts now matches more common structur
 
 Fixed an issue where `pants run ...` commands only worked if the `package.json` file was in the root directory.
 
+The dependency inference now considers `.ts` and `.tsx` file extensions.
+
+The dependency inference now considers scoped npm packages.
+
+The NodeJS subsystem now supports configuring additional tools that should be available in the NodeJS process execution. These tools can be configured via two options:
+
+- [`[nodejs].tools`](https://www.pantsbuild.org/2.25/reference/subsystems/nodejs#tools): Specify additional executables required by nodejs processes.
+- [`[nodejs].optional_tools`](https://www.pantsbuild.org/2.25/reference/subsystems/nodejs#optional_tools): Additional tools that may be needed but aren't required. Unlike `tools`, the build won't fail if these aren't found. Useful for tools that only exist in some environments.
+
+The paths to these tools will be included in the PATH used in the execution sandbox, so that they may be used by NodeJS processes during execution.
+
+##### TypeScript
+
+The dependency inference now considers `.tsx` files.
+
+#### nFPM
+
+The nFPM backend has a new plugin hook that allows plugins to inject field values that are used to generate nfpm config. To use this, a plugin needs to implement `InjectNfpmPackageFieldsRequest`:
+
+```python
+from pants.backend.nfpm.fields.version import NfpmVersionField, NfpmVersionReleaseField
+from pants.backend.nfpm.util_rules.inject_config import InjectedNfpmPackageFields, InjectNfpmPackageFieldsRequest
+from pants.engine.internals.native_engine import Address, Field
+from pants.engine.rules import rule
+
+class MyCustomInjectFieldsRequest(InjectNfpmPackageFieldsRequest):
+    @classmethod
+    def is_applicable(cls, target) -> bool:
+        # this could check the target's address, packager, package_name field, etc.
+        return True
+
+@rule
+def inject_my_custom_fields(request: MyCustomInjectFieldsRequest) -> InjectedNfpmPackageFields:
+    # this could get the version from a file
+    version = "9.8.7-dev+git"
+    release = 6
+    fields: list[Field] = [
+        NfpmVersionField(version, request.target.address),
+        NfpmVersionReleaseField(release, request.target.address),
+    ]
+    return InjectedNfpmPackageFields(fields, address=request.target.address)
+```
+
 #### Python
 
 The AWS Lambda backend now provides built-in complete platforms for the Python 3.13 runtime.
@@ -94,25 +141,20 @@ Constrained the transitive dependencies within the builtin lockfile for twine to
 
 Several improvements to the Python Build Standalone backend (`pants.backend.python.providers.experimental.python_build_standalone`):
 
-- The backend now supports filtering PBS releases via their "release tag" via [the new `--python-build-standalone-release-constraints` option](https://www.pantsbuild.org/2.25/reference/subsystems/python-build-standalone-python-provider#release_constraints). THe PBS "known versions" database now contains metadata on all known PBS versions, and not just the latest PBS release tag per Python patchlevel.
+- The backend now supports filtering PBS releases via their "release tag" via [the new `--python-build-standalone-release-constraints` option](https://www.pantsbuild.org/2.25/reference/subsystems/python-build-standalone-python-provider#release_constraints). The PBS "known versions" database now contains metadata on all known PBS versions, and not just the latest PBS release tag per Python patchlevel.
 
 - The backend will now infer metadata for a PBS release from a given URL if the URL conforms to the naming convention used by the PBS project. The inferred metadata is Python version, PBS release tag, and platform.
 
 - The `--python-build-standalone-known-python-versions` option now accepts a three field format where each value is `SHA256|FILE_SIZE|URL`. All of the PBS release metadata will be parsed from the URL (which must use the naming convention used by the PBS project). (The existing five-field format is still accepted and will now allow the version and platform fields to be blank if that data can be inferred from the URL.)
 
 - Metadata on PBS releases is current to PBS release 20250115.
 
-Changed references to Python Build Standalone to not refer to the [GitHub organization](https://github.com/astral-sh/python-build-standalone) as described in [Transferring Python Build Standalone Stewardship to Astral](https://gregoryszorc.com/blog/2024/12/03/transferring-python-build-standalone-stewardship-to-astral/).
+Changed references to Python Build Standalone to refer to the new [GitHub organization](https://github.com/astral-sh/python-build-standalone) as described in [Transferring Python Build Standalone Stewardship to Astral](https://gregoryszorc.com/blog/2024/12/03/transferring-python-build-standalone-stewardship-to-astral/).
 
 The default version of the [Pex](https://docs.pex-tool.org/) tool has been updated from 2.20.3 to [2.32.1](https://github.com/pex-tool/pex/releases/tag/v2.32.1).  Among many improvements and bug fixes, this unlocks support for pip [24.3.1](https://pip.pypa.io/en/stable/news/#v24-3-1) and Pip [25.0](https://pip.pypa.io/en/stable/news/#v25).
 
 The `pants.backend.experimental.python.lint.ruff.check` backend [now supports](https://github.com/pantsbuild/pants/pull/21783) including [Ruff's output file as a report](https://www.pantsbuild.org/2.25/docs/python/overview/linters-and-formatters#bandit-flake8-pylint-and-ruff-report-files).
 
-#### Go
-
-Fix a bug with the setup of the gRPC protobuf plugins where a `go install` invocation was prevented from accessing the Go module proxy during its build of those plugins, which caused those builds to fail.
-
-
 ##### NEW: Python for OpenAPI
 
 A new experimental `pants.backend.experimental.openapi.codegen.python` backend
@@ -161,51 +203,6 @@ Bugfix: fixed an issue with cache concurrency. This affected initialisation of m
 
 The previously deprecated `[shell-setup].tailor` option has now been removed. See [`[shell-setup].tailor_sources`](https://www.pantsbuild.org/2.25/reference/subsystems/shell-setup#tailor_sources) and [`[shell-setup].tailor_shunit2_tests`](https://www.pantsbuild.org/2.25/reference/subsystems/shell#tailor_shunit2_tests) to update.
 
-#### nFPM
-
-The nFPM backend has a new plugin hook that allows plugins to inject field values that are used to generate nfpm config. To use this, a plugin needs to implement `InjectNfpmPackageFieldsRequest`:
-
-```python
-from pants.backend.nfpm.fields.version import NfpmVersionField, NfpmVersionReleaseField
-from pants.backend.nfpm.util_rules.inject_config import InjectedNfpmPackageFields, InjectNfpmPackageFieldsRequest
-from pants.engine.internals.native_engine import Address, Field
-from pants.engine.rules import rule
-
-class MyCustomInjectFieldsRequest(InjectNfpmPackageFieldsRequest):
-    @classmethod
-    def is_applicable(cls, target) -> bool:
-        # this could check the target's address, packager, package_name field, etc.
-        return True
-
-@rule
-def inject_my_custom_fields(request: MyCustomInjectFieldsRequest) -> InjectedNfpmPackageFields:
-    # this could get the version from a file
-    version = "9.8.7-dev+git"
-    release = 6
-    fields: list[Field] = [
-        NfpmVersionField(version, request.target.address),
-        NfpmVersionReleaseField(release, request.target.address),
-    ]
-    return InjectedNfpmPackageFields(fields, address=request.target.address)
-```
-
-#### JavaScript
-
-The dependency inference now considers `.ts` and `.tsx` file extensions.
-
-The dependency inference now considers scoped npm packages.
-
-The NodeJS subsystem now supports configuring additional tools that should be available in the NodeJS process execution. These tools can be configured via two options:
-
-- [`[nodejs].tools`](https://www.pantsbuild.org/2.25/reference/subsystems/nodejs#tools): Specify additional executables required by nodejs processes.
-- [`[nodejs].optional_tools`](https://www.pantsbuild.org/2.25/reference/subsystems/nodejs#optional_tools): Additional tools that may be needed but aren't required. Unlike `tools`, the build won't fail if these aren't found. Useful for tools that only exist in some environments.
-
-The paths to these tools will be included in the PATH used in the execution sandbox, so that they may be used by NodeJS processes during execution.
-
-#### TypeScript
-
-The dependency inference now considers `.tsx` files.
-
 ### Plugin API changes
 
 The version of Python used by Pants itself is now [3.11](https://docs.python.org/3/whatsnew/3.11.html) (up from 3.9).