You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by hb...@apache.org on 2021/04/04 07:28:03 UTC
[maven] branch master updated: [MNG-6656] add reference
documentation on build/consumer transformers
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/master by this push:
new 87cd496 [MNG-6656] add reference documentation on build/consumer transformers
87cd496 is described below
commit 87cd4960a4fddc289859f1eff8fd94ad57d7c5e6
Author: Hervé Boutemy <hb...@apache.org>
AuthorDate: Sun Apr 4 09:27:59 2021 +0200
[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(+)
diff --git a/maven-xml/src/site/apt/index.apt b/maven-xml/src/site/apt/index.apt
new file mode 100644
index 0000000..b1d5013
--- /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 0000000..e475330
--- /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