From 0b2147bac8318aeb13e5abf1d00b026195da1b53 Mon Sep 17 00:00:00 2001
From: Elliotte Rusty Harold <elharo@ibiblio.org>
Date: Mon, 31 Aug 2026 13:21:40 +0000
Subject: [PATCH 1/2] [MCOMPILER-563] Clarify that incremental compilation is
 not an IDE-style incremental compiler

Improve the Javadoc of the incrementalCompilation and the deprecated
useIncrementalCompilation parameters. Despite the name, the plugin does not
compile a single changed class together with its dependents like an IDE
incremental compiler. It runs a change-detection algorithm that decides
whether to recompile the whole module or only the modified source files.
---
 .../plugin/compiler/AbstractCompilerMojo.java  | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java
index 0c0979584..9907290b8 100644
--- a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java
+++ b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java
@@ -586,7 +586,16 @@ final Charset charset() {
     protected String outputTimestamp;
 
     /**
-     * The algorithm to use for selecting which files to compile.
+     * <b>Despite the word "incremental" in the name, this is <i>not</i> an incremental compiler
+     * in the sense of an IDE.</b> The plugin does not compile a single changed class and the classes
+     * that depend on it. It selects an algorithm used to <i>detect changes</i> and to decide whether
+     * to recompile the whole module or only some source files. In most configurations a change causes
+     * the whole module (all its source files) to be recompiled; see the {@code sources} and
+     * {@code classes} values below, which decide whether only the modified source files are recompiled
+     * or whether a change triggers a full rebuild. The plugin never performs dependency-based
+     * compilation of only the directly or transitively affected classes.
+     *
+     * <p>The algorithm to use for selecting which files to compile.
      * Values can be {@code dependencies}, {@code sources}, {@code classes}, {@code rebuild-on-change},
      * {@code rebuild-on-add}, {@code modules} or {@code none}.
      *
@@ -670,7 +679,12 @@ final Charset charset() {
     protected String incrementalCompilation;
 
     /**
-     * Whether to enable/disable incremental compilation feature.
+     * Whether to enable/disable the change detection that decides when to recompile the module.
+     *
+     * <p>Despite the word "incremental" in this property name, this does <i>not</i> enable an
+     * incremental compiler in the sense of an IDE. The plugin never compiles a single changed class
+     * together with the classes that depend on it. It only detects changes and, depending on the
+     * configuration, recompiles the whole module or only the modified source files.</p>
      *
      * @since 3.1
      *

From 698ea648d4316ac55d61a7353c4d572100d1b40f Mon Sep 17 00:00:00 2001
From: Elliotte Rusty Harold <elharo@users.noreply.github.com>
Date: Mon, 31 Aug 2026 13:36:37 +0000
Subject: [PATCH 2/2] Update AbstractCompilerMojo.java

---
 .../apache/maven/plugin/compiler/AbstractCompilerMojo.java   | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java
index 9907290b8..0d8e2aa83 100644
--- a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java
+++ b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java
@@ -680,11 +680,10 @@ final Charset charset() {
 
     /**
      * Whether to enable/disable the change detection that decides when to recompile the module.
-     *
-     * <p>Despite the word "incremental" in this property name, this does <i>not</i> enable an
+     * Despite the word "incremental", this does not enable an
      * incremental compiler in the sense of an IDE. The plugin never compiles a single changed class
      * together with the classes that depend on it. It only detects changes and, depending on the
-     * configuration, recompiles the whole module or only the modified source files.</p>
+     * configuration, recompiles the whole module or only the modified source files.
      *
      * @since 3.1
      *