From 3bd3f9f2c417011c25a3078badd1927cc0f827ea Mon Sep 17 00:00:00 2001
From: Jan Berkel <jan@berkel.fr>
Date: Wed, 23 Jul 2025 15:17:39 +0200
Subject: [PATCH 1/2] Document current issues using JDKs > 17 and nailgun

---
 docs/docs/jvm/java-and-scala.mdx          | 21 +++++++++++++++++++++
 src/python/pants/option/global_options.py |  8 +++++++-
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/docs/docs/jvm/java-and-scala.mdx b/docs/docs/jvm/java-and-scala.mdx
index c546c0f0db4..14224976654 100644
--- a/docs/docs/jvm/java-and-scala.mdx
+++ b/docs/docs/jvm/java-and-scala.mdx
@@ -66,6 +66,27 @@ JDKs used by Pants are automatically fetched using [Coursier](https://get-coursi
 
 To override the default on a particular target, you can use the [`jdk=` field](../../reference/targets/java_source.mdx#jdk). It can be useful to use the [`parametrize` builtin](../using-pants/key-concepts/targets-and-build-files.mdx#parametrizing-targets) with the `jdk=` field, particularly to run test targets under multiple JDKs.
 
+To get a list of available JDK versions:
+
+```sh
+$ coursier java --available
+adoptium:1.11.0.15
+adoptium:1.11.0.16
+...
+```
+
+Please note that JDKs later than 17 are not supported by nailgun
+(see [#20603](https://github.com/pantsbuild/pants/issues/20603)), which
+must be disabled manually:
+
+```toml title="pants.toml"
+[GLOBAL]
+process_execution_local_enable_nailgun = false
+
+[jvm]
+jdk = "temurin:1.22"
+```
+
 #### Scala version
 
 The Scala version to use is configured on a resolve-by-resolve basis (see the "Third-party dependencies" section below) using the [`[scala].version_for_resolve` option](../../reference/subsystems/scala.mdx#version_for_resolve). The default Scala version for your repository will thus be whichever Scala version is configured for the "default" resolve, which is configured by the [`[jvm].default_resolve` option](../../reference/subsystems/jvm#default_resolve).
diff --git a/src/python/pants/option/global_options.py b/src/python/pants/option/global_options.py
index 7002cf625dd..637aa626a3a 100644
--- a/src/python/pants/option/global_options.py
+++ b/src/python/pants/option/global_options.py
@@ -1453,7 +1453,13 @@ class BootstrapOptions:
     )
     process_execution_local_enable_nailgun = BoolOption(
         default=DEFAULT_EXECUTION_OPTIONS.process_execution_local_enable_nailgun,
-        help="Whether or not to use nailgun to run JVM requests that are marked as supporting nailgun.",
+        help=softwrap(
+            """
+            Whether or not to use nailgun to run JVM requests that are marked as supporting nailgun.
+            Note that nailgun only works correctly on JDK <= 17 and must be disabled manually for
+            later versions.
+            """
+        ),
         advanced=True,
     )
     process_execution_graceful_shutdown_timeout = IntOption(

From 1f71c7a24dfc8abde51c00ca8980929710ea2077 Mon Sep 17 00:00:00 2001
From: Jan Berkel <jan@berkel.fr>
Date: Wed, 23 Jul 2025 16:11:28 +0200
Subject: [PATCH 2/2] Add release notes

---
 docs/notes/2.29.x.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/notes/2.29.x.md b/docs/notes/2.29.x.md
index a78964c7f55..a09092c45e2 100644
--- a/docs/notes/2.29.x.md
+++ b/docs/notes/2.29.x.md
@@ -22,6 +22,10 @@ Adds a label to `docker_environment` containers so pantsd can cleanup any old, d
 
 ### Backends
 
+#### JVM
+
+Document nailgun compatibility issues.
+
 #### Python
 
 The version of [Pex](https://github.com/pex-tool/pex) used by the Python backend has been upgraded to v2.45.2.