Merge pull request #26508 Add upgrade guide paragraph about XML faili…

…ng parser configuration

And enhance `XMLFactories` error messages.

### Reviewing cheatsheet

Before merging the PR, comments starting with
- ❌ ❓**must** be fixed
- 🤔 💅 **should** be fixed
- 💭 **may** be fixed
- 🎉 celebrate happy things

Co-authored-by: Paul Merlin <paul@gradle.com>

subprojects/base-services/src/main/java/org/gradle/internal/xml/XmlFactories.java

@@ -41,7 +41,7 @@ public static DocumentBuilderFactory newDocumentBuilderFactory() {
             dbf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
             return dbf;
         } catch (ParserConfigurationException e) {
-            throw new RuntimeException("Unable to create secure DocumentBuilderFactory", e);
+            throw new RuntimeException(errorMessageFor("DocumentBuilderFactory"), e);
         }
     }
 
@@ -51,11 +51,11 @@ public static SAXParserFactory newSAXParserFactory() {
             spf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
             return spf;
         } catch (ParserConfigurationException e) {
-            throw new RuntimeException("Unable to create secure SAXParserFactory", e);
+            throw new RuntimeException(errorMessageFor("SAXParserFactory"), e);
         } catch (SAXNotSupportedException e) {
-            throw new RuntimeException("Unable to create secure SAXParserFactory", e);
+            throw new RuntimeException(errorMessageFor("SAXParserFactory"), e);
         } catch (SAXNotRecognizedException e) {
-            throw new RuntimeException("Unable to create secure SAXParserFactory", e);
+            throw new RuntimeException(errorMessageFor("SAXParserFactory"), e);
         }
     }
 
@@ -65,7 +65,7 @@ public static XPathFactory newXPathFactory() {
             xpf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
             return xpf;
         } catch (XPathFactoryConfigurationException e) {
-            throw new RuntimeException("Unable to create secure XPathFactory", e);
+            throw new RuntimeException(errorMessageFor("XPathFactory"), e);
         }
     }
 
@@ -75,9 +75,13 @@ public static TransformerFactory newTransformerFactory() {
             tf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
             return tf;
         } catch (TransformerConfigurationException e) {
-            throw new RuntimeException("Unable to create secure TransformerFactory", e);
+            throw new RuntimeException(errorMessageFor("TransformerFactory"), e);
         }
     }
 
+    private static String errorMessageFor(String factory) {
+        return "Unable to create secure " + factory + ", please make sure that your build does not depend on an old XML parser.";
+    }
+
     private XmlFactories() {}
 }

subprojects/docs/src/docs/userguide/releases/upgrading/upgrading_version_8.adoc

@@ -44,6 +44,13 @@ The previous step will help you identify potential problems by issuing deprecati
 
 The embedded Kotlin has been updated to link:https://github.com/JetBrains/kotlin/releases/tag/v1.9.10[Kotlin 1.9.10].
 
+==== XML parsing now requires recent parsers
+
+Gradle 8.4 now configures XML parsers with security features enabled.
+If your build logic has dependencies on old XML parsers that don't support secure parsing your build may now fail.
+If you encounter a failure, check and update or remove any dependency on legacy XML parsers.
+
+
 ==== EAR plugin with customized JEE 1.3 descriptor
 
 Gradle 8.4 forbids external XML entities when parsing XML documents.