From 613bb636513741c7801a44f78275fec0ef7c1394 Mon Sep 17 00:00:00 2001
From: "Piotr P. Karwasz" <pkarwasz-github@apache.org>
Date: Wed, 8 Jul 2026 18:04:25 +0200
Subject: [PATCH 1/2] Add trailing newlines and use American spelling

Add the missing EOL at end of file to the three .github config files,
and convert British spellings (Honoured, flavour(s), synchronise,
standardised, defence) to American in Javadoc, comments, and docs.
---
 .github/dependabot.yml                                      | 2 +-
 .github/workflows/codeql-analysis.yml                       | 2 +-
 .github/workflows/maven.yml                                 | 2 +-
 .../org/apache/commons/xml/DocumentBuilderHardener.java     | 2 +-
 src/main/java/org/apache/commons/xml/Resolvers.java         | 6 +++---
 src/main/java/org/apache/commons/xml/SAXParserHardener.java | 2 +-
 src/main/java/org/apache/commons/xml/XmlFactories.java      | 2 +-
 src/site/markdown/index.md                                  | 4 ++--
 src/test/java/org/apache/commons/xml/AttackTestSupport.java | 6 +++---
 src/test/java/org/apache/commons/xml/BillionLaughsTest.java | 2 +-
 10 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 7125dd48..cc8ef122 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -25,4 +25,4 @@ updates:
     schedule:
       interval: "weekly"
     cooldown:
-      default-days: 7
\ No newline at end of file
+      default-days: 7
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
index fff08656..68247efa 100644
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -32,4 +32,4 @@ jobs:
     permissions:
       actions: read
       contents: read
-      security-events: write
\ No newline at end of file
+      security-events: write
diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml
index 1687801c..21f86f65 100644
--- a/.github/workflows/maven.yml
+++ b/.github/workflows/maven.yml
@@ -198,4 +198,4 @@ jobs:
             android-tests/build/outputs/androidTest-results/
             android-tests/build/reports/androidTests/
           if-no-files-found: ignore
-          retention-days: 14
\ No newline at end of file
+          retention-days: 14
diff --git a/src/main/java/org/apache/commons/xml/DocumentBuilderHardener.java b/src/main/java/org/apache/commons/xml/DocumentBuilderHardener.java
index b0484a03..8ed96e65 100644
--- a/src/main/java/org/apache/commons/xml/DocumentBuilderHardener.java
+++ b/src/main/java/org/apache/commons/xml/DocumentBuilderHardener.java
@@ -91,7 +91,7 @@ static DocumentBuilderFactory harden(final DocumentBuilderFactory factory) {
         // ACCESS_EXTERNAL_* support is the dividing capability between JAXP 1.5 implementations and older ones.
         if (trySetAttribute(factory, XMLConstants.ACCESS_EXTERNAL_DTD, "")
                 && trySetAttribute(factory, XMLConstants.ACCESS_EXTERNAL_SCHEMA, "")) {
-            // Honoured: the JAXP 1.5 properties block external fetches, so the bare factory is already hardened.
+            // Honored: the JAXP 1.5 properties block external fetches, so the bare factory is already hardened.
             return factory;
         }
         // Rejected: external Xerces ignores ACCESS_EXTERNAL_*; install a deny-all resolver on every DocumentBuilder.
diff --git a/src/main/java/org/apache/commons/xml/Resolvers.java b/src/main/java/org/apache/commons/xml/Resolvers.java
index 63556c40..db497e33 100644
--- a/src/main/java/org/apache/commons/xml/Resolvers.java
+++ b/src/main/java/org/apache/commons/xml/Resolvers.java
@@ -33,7 +33,7 @@
 /**
  * Stateless resolver singletons that fix the outcome of every external lookup.
  *
- * <p>Two flavours are exposed, each as a typed singleton field per resolver interface:</p>
+ * <p>Two flavors are exposed, each as a typed singleton field per resolver interface:</p>
  * <ul>
  *     <li>{@link DenyAll} refuses every lookup with an exception. Use this on schema/XSLT compile paths and on parser entity hooks where any external fetch is
  *         a hardening violation.</li>
@@ -43,7 +43,7 @@
  *
  * <p>{@link XMLResolver} and {@link EntityResolver2} both declare a 4-arg {@code resolveEntity(String, String, String, String)} with identical erasure but
  * different parameter semantics, return types ({@link Object} vs {@link InputSource}) and throws clauses ({@link XMLStreamException} vs {@link SAXException}),
- * so they cannot coexist on the same class. Each flavour therefore exposes its {@code XMLResolver} and {@code EntityResolver2} singletons separately.</p>
+ * so they cannot coexist on the same class. Each flavor therefore exposes its {@code XMLResolver} and {@code EntityResolver2} singletons separately.</p>
  */
 final class Resolvers {
 
@@ -113,7 +113,7 @@ private DenyAll() {
     /**
      * Returns an empty input for every external resource lookup so the parse can continue without replacement content.
      *
-     * <p>Only an {@link XMLResolver} flavour is exposed: schema and XSLT compile paths must always deny imports, and SAX/DOM use the deny-all hooks.</p>
+     * <p>Only an {@link XMLResolver} flavor is exposed: schema and XSLT compile paths must always deny imports, and SAX/DOM use the deny-all hooks.</p>
      */
     static final class IgnoreAll {
 
diff --git a/src/main/java/org/apache/commons/xml/SAXParserHardener.java b/src/main/java/org/apache/commons/xml/SAXParserHardener.java
index 7b1fb7de..8f6684f0 100644
--- a/src/main/java/org/apache/commons/xml/SAXParserHardener.java
+++ b/src/main/java/org/apache/commons/xml/SAXParserHardener.java
@@ -175,7 +175,7 @@ static XMLReader hardenReader(final XMLReader reader) {
         // ACCESS_EXTERNAL_* support is the dividing capability between JAXP 1.5 implementations and older ones.
         if (trySetProperty(reader, XMLConstants.ACCESS_EXTERNAL_DTD, "")
                 && trySetProperty(reader, XMLConstants.ACCESS_EXTERNAL_SCHEMA, "")) {
-            // Honoured (stock JDK): the JAXP 1.5 properties block external fetches, so the bare reader is already hardened.
+            // Honored (stock JDK): the JAXP 1.5 properties block external fetches, so the bare reader is already hardened.
             return reader;
         }
         // Rejected: external Xerces ignores ACCESS_EXTERNAL_*; install a deny-all resolver, the only block.
diff --git a/src/main/java/org/apache/commons/xml/XmlFactories.java b/src/main/java/org/apache/commons/xml/XmlFactories.java
index 41056ffa..a5b5c6d1 100644
--- a/src/main/java/org/apache/commons/xml/XmlFactories.java
+++ b/src/main/java/org/apache/commons/xml/XmlFactories.java
@@ -67,7 +67,7 @@
  * <h2>Thread safety</h2>
  *
  * <p>The returned factories inherit the thread-safety properties of the underlying JAXP implementation, which in practice means they are <strong>not
- * guaranteed to be thread-safe</strong>. Create a new factory per thread or synchronise externally.</p>
+ * guaranteed to be thread-safe</strong>. Create a new factory per thread or synchronize externally.</p>
  *
  * <p>This class itself is thread-safe: all methods are static and stateless.</p>
  */
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index daa877b2..98cc59e0 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -30,7 +30,7 @@ stock JDK and external JAXP implementations.
 
 Any Java library that parses XML has to harden JAXP before handing a factory to user code, and every library ends up
 copy-pasting the same hardening snippet. The snippet is fragile: the attributes and features needed to harden a factory
-are not standardised, each JAXP implementation exposes a slightly different set, and setting an unknown one throws an
+are not standardized, each JAXP implementation exposes a slightly different set, and setting an unknown one throws an
 exception that callers routinely swallow. Writing this block correctly for every implementation is real work, and
 duplicating it across projects means every project owns the maintenance burden on its own.
 
@@ -142,5 +142,5 @@ pass the result as a `DOMSource` or `SAXSource`.
 
 There is no caching or pooling inside `XmlFactories`; callers on a hot path are responsible for their own caching. The
 returned factories inherit the thread-safety properties of the underlying JAXP implementation, which in practice means
-they are not thread-safe. Create a new factory per thread or synchronise externally.
+they are not thread-safe. Create a new factory per thread or synchronize externally.
 
diff --git a/src/test/java/org/apache/commons/xml/AttackTestSupport.java b/src/test/java/org/apache/commons/xml/AttackTestSupport.java
index 9b6c07f1..b64751a5 100644
--- a/src/test/java/org/apache/commons/xml/AttackTestSupport.java
+++ b/src/test/java/org/apache/commons/xml/AttackTestSupport.java
@@ -54,7 +54,7 @@
 /**
  * Shared fixtures for attack tests.
  *
- * <p>The hardened-side helpers come in three flavours, distinguished by their suffix:</p>
+ * <p>The hardened-side helpers come in three flavors, distinguished by their suffix:</p>
  *
  * <ul>
  *   <li>{@code assert*Blocks(...)} runs the payload through a hardened factory from {@link XmlFactories} and asserts the parse throws. Used when the hardening
@@ -452,7 +452,7 @@ static void assertSchemaDoesNotLeak(final Source xsd) {
     /**
      * Asserts a hardened StAX parse of the payload throws.
      *
-     * <p>{@link XMLStreamReader} and {@link XMLEventReader} from {@link XmlFactories#newXMLInputFactory()}; both flavours are exercised and either must
+     * <p>{@link XMLStreamReader} and {@link XMLEventReader} from {@link XmlFactories#newXMLInputFactory()}; both flavors are exercised and either must
      * throw.</p>
      */
     static void assertStaxBlocks(final String payload) {
@@ -463,7 +463,7 @@ static void assertStaxBlocks(final String payload) {
     /**
      * Asserts a hardened StAX parse completes without throwing and without leaked content.
      *
-     * <p>{@link XMLStreamReader} and {@link XMLEventReader} from {@link XmlFactories#newXMLInputFactory()}; both flavours are exercised. Use this when the
+     * <p>{@link XMLStreamReader} and {@link XMLEventReader} from {@link XmlFactories#newXMLInputFactory()}; both flavors are exercised. Use this when the
      * hardening guarantee is "the parse succeeds but never resolves the external resource", e.g. when the JDK's {@code ignore-external-dtd} property silently
      * skips the external subset.</p>
      */
diff --git a/src/test/java/org/apache/commons/xml/BillionLaughsTest.java b/src/test/java/org/apache/commons/xml/BillionLaughsTest.java
index eb18e72e..164839a1 100644
--- a/src/test/java/org/apache/commons/xml/BillionLaughsTest.java
+++ b/src/test/java/org/apache/commons/xml/BillionLaughsTest.java
@@ -45,7 +45,7 @@
  * <p>Which fixture each test uses:</p>
  *
  * <ul>
- *   <li>{@code hardened*} tests pull from {@code hardened*Payload} helpers: large fixture on Android (libexpat is the only defence), medium fixture on JDK
+ *   <li>{@code hardened*} tests pull from {@code hardened*Payload} helpers: large fixture on Android (libexpat is the only defense), medium fixture on JDK
  *       (entity-expansion count limit is sufficient).</li>
  *   <li>{@code unconfigured*} positive controls pull from {@code medium*Payload} helpers regardless of platform: libexpat's billion-laughs check cannot be
  *       disabled from Java, so a permissive parse of the large fixture would still trip on Android.</li>

From de79d60d79d0d71804337d711f6c5a44ac344e58 Mon Sep 17 00:00:00 2001
From: "Piotr P. Karwasz" <pkarwasz-github@apache.org>
Date: Wed, 8 Jul 2026 18:12:13 +0200
Subject: [PATCH 2/2] Replace Latin abbreviations with English phrases

Spell out e.g. as "for example", i.e. as "that is", and etc. as
"and so on" in Javadoc and comments. Leaves the upstream
CONTRIBUTING.md boilerplate and the spotbugs URL path untouched.
---
 src/main/java/org/apache/commons/xml/Limits.java   |  2 +-
 .../org/apache/commons/xml/SAXParserHardener.java  |  2 +-
 .../org/apache/commons/xml/AttackTestSupport.java  | 14 +++++++-------
 .../java/org/apache/commons/xml/NoDoctypeTest.java |  2 +-
 .../org/apache/commons/xml/DescriptorIT.java       |  4 ++--
 5 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/src/main/java/org/apache/commons/xml/Limits.java b/src/main/java/org/apache/commons/xml/Limits.java
index ec00834f..48297110 100644
--- a/src/main/java/org/apache/commons/xml/Limits.java
+++ b/src/main/java/org/apache/commons/xml/Limits.java
@@ -97,7 +97,7 @@ final class Limits {
      */
     private static final int DEFAULT_MAX_ELEMENT_DEPTH = 100;
     /**
-     * Maximum length, in characters, of an XML name (element name, attribute name, namespace prefix, etc); JDK 25 secure value.
+     * Maximum length, in characters, of an XML name (element name, attribute name, namespace prefix, and so on); JDK 25 secure value.
      *
      * <p>Override with system property {@value #SP_MAX_NAME_LIMIT}.</p>
      *
diff --git a/src/main/java/org/apache/commons/xml/SAXParserHardener.java b/src/main/java/org/apache/commons/xml/SAXParserHardener.java
index 8f6684f0..ea760665 100644
--- a/src/main/java/org/apache/commons/xml/SAXParserHardener.java
+++ b/src/main/java/org/apache/commons/xml/SAXParserHardener.java
@@ -154,7 +154,7 @@ static SAXParserFactory harden(final SAXParserFactory factory) {
      */
     static XMLReader hardenReader(final XMLReader reader) {
         if (reader instanceof ExpatReaderWrapper) {
-            // Already hardened (e.g. handed back through XmlFactories.harden(XMLReader)); applying the Expat fixups again would be redundant.
+            // Already hardened (for example, handed back through XmlFactories.harden(XMLReader)); applying the Expat fixups again would be redundant.
             return reader;
         }
         if (ANDROID_EXPAT_READER.equals(reader.getClass().getName())) {
diff --git a/src/test/java/org/apache/commons/xml/AttackTestSupport.java b/src/test/java/org/apache/commons/xml/AttackTestSupport.java
index b64751a5..32997b2a 100644
--- a/src/test/java/org/apache/commons/xml/AttackTestSupport.java
+++ b/src/test/java/org/apache/commons/xml/AttackTestSupport.java
@@ -60,11 +60,11 @@
  *   <li>{@code assert*Blocks(...)} runs the payload through a hardened factory from {@link XmlFactories} and asserts the parse throws. Used when the hardening
  *       layer is expected to reject the attack outright.</li>
  *   <li>{@code assert*DoesNotLeak(...)} runs the payload through a hardened factory and asserts the parse completes without throwing and without producing the
- *       {@link #LEAKED_MARKER} string. Used when the hardening contract guarantees the parse succeeds but never resolves the external resource (e.g.
+ *       {@link #LEAKED_MARKER} string. Used when the hardening contract guarantees the parse succeeds but never resolves the external resource (for example,
  *       {@code XERCES_LOAD_EXTERNAL_DTD=false} silently skipping the external subset, with the body's undeclared entity reference dropped per XML 1.0
  *       §4.1).</li>
  *   <li>{@code assert*BlocksOrDoesNotLeak(...)} accepts either of the previous two outcomes. Used where the same hardening contract surfaces differently across
- *       providers (e.g. stock-JDK XSLTC throws via {@code ACCESS_EXTERNAL_DTD} while Apache Xalan silently skips because its source-rewrite routes parsing
+ *       providers (for example, stock-JDK XSLTC throws via {@code ACCESS_EXTERNAL_DTD} while Apache Xalan silently skips because its source-rewrite routes parsing
  *       through a {@code XERCES_LOAD_EXTERNAL_DTD=false} reader).</li>
  * </ul>
  *
@@ -185,7 +185,7 @@ static void assertDomBlocks(final String payload) {
      * Asserts a hardened DOM parse completes without throwing and without leaked content.
      *
      * <p>{@link DocumentBuilder#parse(InputSource)} via {@link XmlFactories#newDocumentBuilderFactory()}; use this when the hardening guarantee is "the parse
-     * succeeds but never resolves the external resource", e.g. when {@code XERCES_LOAD_EXTERNAL_DTD=false} silently skips the external subset.</p>
+     * succeeds but never resolves the external resource", for example, when {@code XERCES_LOAD_EXTERNAL_DTD=false} silently skips the external subset.</p>
      */
     static void assertDomDoesNotLeak(final String payload) {
         assertNoLeakStrict(() -> domParseAndCaptureText(payload), "DOM");
@@ -204,7 +204,7 @@ static void assertDomParses(final String payload) {
      * Skeleton for every {@code assert*BlocksOrDoesNotLeak} helper.
      *
      * <p>Treats a thrown exception of one of the {@code expected} types as "hardening blocked at parse" (acceptable); otherwise asserts the captured output
-     * omits {@link #LEAKED_MARKER}. A throw whose type does not match {@code expected} fails the test, so unrelated failures (e.g. a {@link HardeningException}
+     * omits {@link #LEAKED_MARKER}. A throw whose type does not match {@code expected} fails the test, so unrelated failures (for example, a {@link HardeningException}
      * because no recipe matched the JAXP implementation) cannot be silently accepted as a clean block.</p>
      *
      * @param action      the parse to execute, returning the captured output text checked for {@link #LEAKED_MARKER}.
@@ -405,7 +405,7 @@ static void assertSaxBlocks(final String payload) {
      * Asserts a hardened SAX parse completes without throwing and without leaked content.
      *
      * <p>{@link XMLReader#parse(InputSource)} on a parser from {@link XmlFactories#newSAXParserFactory()}; use this when the hardening guarantee is "the parse
-     * succeeds but never resolves the external resource", e.g. when {@code XERCES_LOAD_EXTERNAL_DTD=false} silently skips the external subset.</p>
+     * succeeds but never resolves the external resource", for example, when {@code XERCES_LOAD_EXTERNAL_DTD=false} silently skips the external subset.</p>
      */
     static void assertSaxDoesNotLeak(final String payload) {
         assertNoLeakStrict(() -> captureCharacters(strictXMLReader(XmlFactories.newSAXParserFactory()), payload), "SAX");
@@ -442,7 +442,7 @@ static void assertSchemaCompiles(final Source xsd) {
      * Asserts a hardened Schema compilation completes without throwing.
      *
      * <p>{@link SchemaFactory#newSchema(Source)} via {@link XmlFactories#newSchemaFactory()}; use this when the hardening contract guarantees the compile
-     * succeeds but never resolves the external resource (e.g. {@code XERCES_LOAD_EXTERNAL_DTD=false} silently skipping the external subset, with the body's
+     * succeeds but never resolves the external resource (for example, {@code XERCES_LOAD_EXTERNAL_DTD=false} silently skipping the external subset, with the body's
      * undeclared entity reference dropped per XML 1.0 §4.1).</p>
      */
     static void assertSchemaDoesNotLeak(final Source xsd) {
@@ -464,7 +464,7 @@ static void assertStaxBlocks(final String payload) {
      * Asserts a hardened StAX parse completes without throwing and without leaked content.
      *
      * <p>{@link XMLStreamReader} and {@link XMLEventReader} from {@link XmlFactories#newXMLInputFactory()}; both flavors are exercised. Use this when the
-     * hardening guarantee is "the parse succeeds but never resolves the external resource", e.g. when the JDK's {@code ignore-external-dtd} property silently
+     * hardening guarantee is "the parse succeeds but never resolves the external resource", for example, when the JDK's {@code ignore-external-dtd} property silently
      * skips the external subset.</p>
      */
     static void assertStaxDoesNotLeak(final String payload) {
diff --git a/src/test/java/org/apache/commons/xml/NoDoctypeTest.java b/src/test/java/org/apache/commons/xml/NoDoctypeTest.java
index a6536e01..e95335b0 100644
--- a/src/test/java/org/apache/commons/xml/NoDoctypeTest.java
+++ b/src/test/java/org/apache/commons/xml/NoDoctypeTest.java
@@ -24,7 +24,7 @@
  * Checks that a plain document without a {@code DOCTYPE} declaration parses cleanly through every hardened JAXP surface.
  *
  * <p>This is the realistic 99% case for hardened input; the hardening contract being verified is "documents without a DOCTYPE parse cleanly through every
- * JAXP surface" so accidental tightening (e.g. a resolver that refuses the synthetic-external-subset hook) is caught.</p>
+ * JAXP surface" so accidental tightening (for example, a resolver that refuses the synthetic-external-subset hook) is caught.</p>
  */
 class NoDoctypeTest {
 
diff --git a/src/test/java11/org/apache/commons/xml/DescriptorIT.java b/src/test/java11/org/apache/commons/xml/DescriptorIT.java
index f2750181..28a1c966 100644
--- a/src/test/java11/org/apache/commons/xml/DescriptorIT.java
+++ b/src/test/java11/org/apache/commons/xml/DescriptorIT.java
@@ -118,7 +118,7 @@ private static JarEntry findModuleInfo(final JarFile jar) {
     }
 
     /**
-     * Returns whether {@code pkg} is exported by an OSGi system bundle, i.e. it sits under one of {@link #PLATFORM_PACKAGE_PREFIXES}.
+     * Returns whether {@code pkg} is exported by an OSGi system bundle, that is, it sits under one of {@link #PLATFORM_PACKAGE_PREFIXES}.
      */
     private static boolean isPlatformPackage(final String pkg) {
         for (final String prefix : PLATFORM_PACKAGE_PREFIXES) {
@@ -150,7 +150,7 @@ private static List<String> splitClauses(final String header) {
     }
 
     /**
-     * Returns the package name of a clause, i.e. everything before its first {@code ;} attribute separator.
+     * Returns the package name of a clause, that is, everything before its first {@code ;} attribute separator.
      */
     private static String packageName(final String clause) {
         final int semicolon = clause.indexOf(';');