From 308a66cc55678bdf9c16e1fd40713451e12d7f79 Mon Sep 17 00:00:00 2001
From: Mikhail Polivakha <68962645+mipo256@users.noreply.github.com>
Date: Wed, 6 Nov 2024 14:31:35 +0300
Subject: [PATCH] Clarified documentation for kotlin compilation with maven
 plugin

---
 docs/topics/maven.md | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/docs/topics/maven.md b/docs/topics/maven.md
index 12832283f21..765de8b2d1c 100644
--- a/docs/topics/maven.md
+++ b/docs/topics/maven.md
@@ -182,12 +182,10 @@ making sure that the `kotlin` plugin comes before the `maven-compiler-plugin` in
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.5.1</version>
             <executions>
-                <!-- Replacing default-compile as it is treated specially by Maven -->
                 <execution>
                     <id>default-compile</id>
                     <phase>none</phase>
                 </execution>
-                <!-- Replacing default-testCompile as it is treated specially by Maven -->
                 <execution>
                     <id>default-testCompile</id>
                     <phase>none</phase>
@@ -212,6 +210,29 @@ making sure that the `kotlin` plugin comes before the `maven-compiler-plugin` in
 </build>
 ```
 
+There are a couple of notes to make here. First, since Maven 3.0.3, the plugins that bound to the same phase have specific execution order. 
+In particular, if plugin `A` is bind to phase `compile` and plugin `B` is bind to phase `compile`, then whoever is executed first is resolved by
+their declaration order in the `pom.xml`. It simply means if `A` is declared before `B` in `pom.xml`, the `A` will be executed prior to `B`. However,
+the built-in plugins native executions, like for plugins `maven-compiler-plugin`, `maven-jar-plugin` e.t.c are executed first regardless of their 
+order in `pom.xml`. Their execution ids are typically named `default-_someting_`. 
+
+Therefore, by specifying the following execution for `maven-compiler-plugin`: 
+
+```
+<execution>
+    <id>default-compile</id>
+    <phase>none</phase>
+</execution>
+<execution>
+    <id>default-testCompile</id>
+    <phase>none</phase>
+</execution>
+```
+
+we're effectively disabling the default executions of `maven-compiler-plugin`. Please, note, that usage of phase 'none' is just a well-known workaround for
+disabling the particualr execution of plugin in Maven. By disabling `default-compile` and `default-testCompile` executions, the new executions `java-compile`
+and not treated as predefined, therefore, and hence the `kotlin-maven-plugin`, as it is declared first, takes precedence. 
+
 ## Enable incremental compilation
 
 To make your builds faster, you can enable incremental compilation by adding the `kotlin.compiler.incremental` property: