From 87cd4960a4fddc289859f1eff8fd94ad57d7c5e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Herv=C3=A9=20Boutemy?= <hboutemy@apache.org>
Date: Sun, 4 Apr 2021 09:27:59 +0200
Subject: [PATCH] [MNG-6656] add reference documentation on build/consumer
 transformers

---
 maven-xml/src/site/apt/index.apt | 73 ++++++++++++++++++++++++++++++++
 maven-xml/src/site/site.xml      | 38 +++++++++++++++++
 2 files changed, 111 insertions(+)
 create mode 100644 maven-xml/src/site/apt/index.apt
 create mode 100644 maven-xml/src/site/site.xml

diff --git a/maven-xml/src/site/apt/index.apt b/maven-xml/src/site/apt/index.apt
new file mode 100644
index 0000000000..b1d501332c
--- /dev/null
+++ b/maven-xml/src/site/apt/index.apt
@@ -0,0 +1,73 @@
+~~ 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.
+
+ -----
+ Introduction
+ -----
+ Hervé Boutemy
+ -----
+ 2021-04-04
+ -----
+
+Maven Model XML Transformer
+
+ Maven Model XML Transformer provides build/consumer <<<pom.xml>>> transformers.
+
+ In order to keep formatting, comments and every detail when transforming a build <<<pom.xml>>> to a consumer <<<pom.xml>>>, transformation happens directly on the stream of SAX events. 
+
+ There are 3 states of a <<<pom.xml>>> content:
+ 
+ [[1]] the <<build>> <<<pom.xml>>>, as it is stored on disk during development and in source control, which can be simplified to ease source code maintenance,
+ 
+ [[2]] the <<raw>> content (usually not saved to a file), which is enriched from initial build content, to match Maven Model validation rules,
+ 
+ [[3]] the <<consumer>> <<<pom.xml>>>, as it is saved to local repository or remote repository, to be used as dependencies descriptor when consumed by a project.
+
+ []
+
+ Transformation is implemented as two filters:
+
+ * <<build to raw>> in <<<BuildPomXMLFilter>>> ({{{./apidocs/org/apache/maven/xml/sax/filter/BuildPomXMLFilter.html}javadoc}}),
+   with its <<<BuildPomXMLFilterFactory>>> ({{{./xref/org/apache/maven/xml/sax/filter/BuildPomXMLFilterFactory.html}source}}) assembling transformation steps,
+
+   * in a multi-module build, <<<parent>>>'s <<<version>>> is automatically added,
+
+   * in a multi-module build, dependencies <<<version>>> is automatically added for reactor modules,
+
+   * CI-friendly <<<$\{sha1}>>>, <<<$\{revision}>>> and <<<$\{changelist}>>> are properties are replaced with their value,
+
+   []
+
+ * <<raw to consumer>> in <<<ConsumerPomXMLFilter>>>  ({{{./apidocs/org/apache/maven/xml/sax/filter/ConsumerPomXMLFilter.html}javadoc}}),
+   with its <<<ConsumerPomXMLFilterFactory>>> ({{{./xref/org/apache/maven/xml/sax/filter/ConsumerPomXMLFilterFactory.html}source}}) assembling transformation steps.
+
+   * <<<modules>>> is stripped because it only has a meaning at build time on disk, but not once mapped to repository format,
+
+   * <<<parent>>>'s <<<relativePath>>> is stripped because it only has a meaning at build time on disk, but not once mapped to repository format.
+
+   []
+
+ []
+
+ For Maven 4, every state of Maven Model remains with the same <<<maven-4.0.0.xsd>>> schema, but it the future Maven 5+:
+ 
+ * build model should evolve to add new features configuration in new <v5> model fields, or remove some old unused fields,
+
+ * consumer model should at least continue to produce a <<<maven-4.0.0.xsd>>>-compliant <<<pom.xml>>> for compatibility with the vast and diverse dependency consumers ecosystem,
+   but may also produce in parallel new consumption formats (yet to be defined).
+
+ []
diff --git a/maven-xml/src/site/site.xml b/maven-xml/src/site/site.xml
new file mode 100644
index 0000000000..e475330c40
--- /dev/null
+++ b/maven-xml/src/site/site.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+
+<project xmlns="http://maven.apache.org/DECORATION/1.8.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 http://maven.apache.org/xsd/decoration-1.8.0.xsd">
+
+  <edit>${project.scm.url}</edit>
+
+  <body>
+    <menu name="Overview">
+      <item name="Introduction" href="index.html"/>
+      <item name="JavaDocs" href="apidocs/index.html"/>
+      <item name="Source Xref" href="xref/index.html"/>
+      <!--item name="FAQ" href="faq.html"/-->
+    </menu>
+
+    <menu ref="parent"/>
+    <menu ref="reports"/>
+  </body>
+</project>
\ No newline at end of file