From 4c906688ff190404a588a6feb9ab67b5d061a377 Mon Sep 17 00:00:00 2001
From: Guillaume Nodet <gnodet@gmail.com>
Date: Thu, 22 Aug 2024 17:10:11 +0200
Subject: [PATCH 1/3] [MNG-7914] Add doc

---
 src/site/markdown/configuring.md | 100 +++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 src/site/markdown/configuring.md

diff --git a/src/site/markdown/configuring.md b/src/site/markdown/configuring.md
new file mode 100644
index 000000000000..780c0d0995f5
--- /dev/null
+++ b/src/site/markdown/configuring.md
@@ -0,0 +1,100 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Configuring Apache Maven
+
+## System properties and JVM
+
+The `MAVEN_OPTS` environment variable contains parameters used to 
+start up the JVM running Maven and can be used to supply additional 
+options to it. For example, JVM memory settings could be defined 
+with the value `-Xms256m -Xmx512m`.
+
+JVM options can also be configured in the 
+`${session.rootDirectory}/.mvn/jvm.config` file, which means you can 
+define the options for your build on a per-project basis. This file 
+will become part of your project and will be checked in along with 
+your project.
+
+So for example if you put the following JVM options into the 
+`.mvn/jvm.config` file:
+```
+-Xmx2048m -Xms1024m -XX:MaxPermSize=512m -Djava.awt.headless=true
+```
+
+The content of this file will be appended to the `MAVEN_OPTS` 
+environment variable.
+
+Note that the above mechanism is handled by the Maven launch 
+scripts `mvn` and `mvnDebug` (`mvn.cmd` and `mvnDebug.cmd` on 
+Windows platforms).
+
+## User Properties
+
+Once the JVM is started, Maven uses _user properties_ to configure
+various parts of the system. The main entry point is the 
+`${maven.home}/conf/maven.properties` properties file. This file,
+along with any other files loaded from it (see below) are called
+_Maven properties files_ and are Java properties files with a 
+few enhancements. Contrary to standard properties file, those files 
+are UTF-8 encoded.
+ 
+### File inclusion
+
+Additional files can be loaded using the special `${includes}` key. 
+The associated value is a comma separated list of additional files to 
+include. Each item may be enclosed in quotes to gracefully include spaces. 
+Items are trimmed before being loaded.  If the first character of an item 
+is a question mark, the load will silently fail if the file does not exist.
+```
+${includes} = ?"${maven.user.conf}/maven.properties", \
+              ?"${maven.project.conf}/maven.properties"
+```
+
+### Property substitution
+
+Properties undergo the _property substitution_ process, so that any 
+value containing a `${xxx}` placeholder will be substituted with the value 
+of the `xxx` property. In addition to properties defined in the files
+being loaded, the following properties are defined:
+* `session.topDirectory`
+* `session.rootDirectory`
+* `maven.version`
+* `maven.build.version`
+* `env.XYZ` to refer to the `XYZ` environment variable
+* `cli.OPT` to refer to the `OPT` command line option
+* system properties
+
+The main `${maven.home}/conf/maven.properties` defines a few basic properties,
+but more importantly, loads the _user_ properties from `~/.m2/maven.properties`
+and the _project_ specific properties from `${session.rootDirectory}/.mvn/maven.properties`.
+
+## Settings
+
+## Extensions
+
+## Maven Command Line Arguments
+
+Maven is a command line tool, and, as such, accepts various command
+line arguments.  The `MAVEN_ARGS` environment value is used to
+provide additional arguments to Maven.  Those arguments will be
+pre-pended to the actual list of command line arguments.
+
+For example, options and goals could be defined with the value
+`-B -V checkstyle:checkstyle`.
+

From 66c590903094a00750e678ed8aaed9eb034cd3b8 Mon Sep 17 00:00:00 2001
From: Guillaume Nodet <gnodet@gmail.com>
Date: Thu, 22 Aug 2024 17:15:55 +0200
Subject: [PATCH 2/3] Add doc

---
 apache-maven/src/assembly/maven/conf/maven.properties | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apache-maven/src/assembly/maven/conf/maven.properties b/apache-maven/src/assembly/maven/conf/maven.properties
index 7c1d76bf563e..ed8989db8d41 100644
--- a/apache-maven/src/assembly/maven/conf/maven.properties
+++ b/apache-maven/src/assembly/maven/conf/maven.properties
@@ -1,6 +1,9 @@
 #
 # Maven user properties
 #
+# The properties defined in this file will be made available through
+# user properties at the very beginning of the Maven's boot process.
+#
 
 maven.installation.conf = ${maven.home}/conf
 maven.user.conf         = ${user.home}/.m2

From 0301ad6d96c65f57c53a1aa4eca06af369c3fa2b Mon Sep 17 00:00:00 2001
From: Guillaume Nodet <gnodet@gmail.com>
Date: Tue, 27 Aug 2024 21:06:36 +0200
Subject: [PATCH 3/3] Fixes from PR review

---
 apache-maven/src/assembly/maven/conf/maven.properties | 2 +-
 src/site/markdown/configuring.md                      | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/apache-maven/src/assembly/maven/conf/maven.properties b/apache-maven/src/assembly/maven/conf/maven.properties
index ed8989db8d41..e1803ccdfa7f 100644
--- a/apache-maven/src/assembly/maven/conf/maven.properties
+++ b/apache-maven/src/assembly/maven/conf/maven.properties
@@ -2,7 +2,7 @@
 # Maven user properties
 #
 # The properties defined in this file will be made available through
-# user properties at the very beginning of the Maven's boot process.
+# user properties at the very beginning of Maven's boot process.
 #
 
 maven.installation.conf = ${maven.home}/conf
diff --git a/src/site/markdown/configuring.md b/src/site/markdown/configuring.md
index 780c0d0995f5..6d7744d3008c 100644
--- a/src/site/markdown/configuring.md
+++ b/src/site/markdown/configuring.md
@@ -54,10 +54,10 @@ _Maven properties files_ and are Java properties files with a
 few enhancements. Contrary to standard properties file, those files 
 are UTF-8 encoded.
  
-### File inclusion
+### File Inclusion
 
 Additional files can be loaded using the special `${includes}` key. 
-The associated value is a comma separated list of additional files to 
+The associated value is a comma-separated list of additional files to 
 include. Each item may be enclosed in quotes to gracefully include spaces. 
 Items are trimmed before being loaded.  If the first character of an item 
 is a question mark, the load will silently fail if the file does not exist.
@@ -66,7 +66,7 @@ ${includes} = ?"${maven.user.conf}/maven.properties", \
               ?"${maven.project.conf}/maven.properties"
 ```
 
-### Property substitution
+### Property Substitution
 
 Properties undergo the _property substitution_ process, so that any 
 value containing a `${xxx}` placeholder will be substituted with the value 
@@ -93,7 +93,7 @@ and the _project_ specific properties from `${session.rootDirectory}/.mvn/maven.
 Maven is a command line tool, and, as such, accepts various command
 line arguments.  The `MAVEN_ARGS` environment value is used to
 provide additional arguments to Maven.  Those arguments will be
-pre-pended to the actual list of command line arguments.
+prepended to the actual list of command line arguments.
 
 For example, options and goals could be defined with the value
 `-B -V checkstyle:checkstyle`.