[james-project] 11/16: JAMES-2124 updates contribution documentation

[bt...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git

commit 288f7fcb57feda978a9c1f841028c710b79e6ef6
Author: Jean Helou <jh...@codamens.fr>
AuthorDate: Thu Nov 19 10:53:46 2020 +0100

    JAMES-2124 updates contribution documentation
---
 docs/modules/community/pages/contributing.adoc | 30 +++++++++++++++-----------
 src/site/xdoc/contribute.xml                   | 14 +++++++++---
 2 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/docs/modules/community/pages/contributing.adoc b/docs/modules/community/pages/contributing.adoc
index 7691e4e..6e6c6cb 100644
--- a/docs/modules/community/pages/contributing.adoc
+++ b/docs/modules/community/pages/contributing.adoc
@@ -110,7 +110,7 @@ https://www.oracle.com/java/technologies/javase/codeconventions-contents.html[Ja
 for fixing their own code.*
 
 . Your code should pass our https://github.com/apache/james-project/blob/master/checkstyle.xml[checkstyle] which runs
-upon mvn clean install.
+upon `mvn compile` and all phases which depend on `compile`.
 . Extra spaces between parentheses are not allowed:
 
 ```
@@ -134,18 +134,22 @@ GREATLY appreciated as this will help to improve the James project.
 
 ** Define your dependency versions in james-project pom.xml. This structurally ensures all projects get the same v
 ersion, and that there is no version clashes.
-** Don't use _org.apache.james_ groupId for your dependencies. Use _${james.groupId}_. If not, you break the policies
-for automatic sorting, as well as make it more ambiguous.
-** You should be ordering your dependencies. The sort order is:
-*** If the project is part of org.james.apache groupId? Internal dependencies goes first.
-*** Then we order by groupId
-*** Then we order by artifactId
-*** Then we order by type. test-jar goes last.
-
-You should also split multiple attributes each on a new line.
-
-You should ensure your POM files, as well as sections ordering follow the
-https://maven.apache.org/ref/3.0.3/maven-model/maven.html[Maven Model].
+** Don't use _org.apache.james_ groupId for internal dependencies. Use _${james.groupId}_. If not, you break the policies
+for automatic sorting, as well as make it more ambiguous. One exception is apache-mime4j-* artifacts which share the
+james groupId despite living in a different repository.
+** You should be ordering your dependencies. The sort order of tags and dependencies in the pom is automatically enforced at build time. By default the build
+will fail if violations are detected.
+
+The pom file ordering can be quickly checked using :
+```
+mvn validate
+```
+If you get an error and want the tool to fix it for you, you can use :
+```
+mvn validate -PsortPom
+```
+The `sortPom` profile can be used on all maven phases. Make sure to review the changes made by the tool, it is known to
+sometimes remove whitespaces which may not be desirable.
 
 === Code patches
 
diff --git a/src/site/xdoc/contribute.xml b/src/site/xdoc/contribute.xml
index 1cb9fc1..1af5ddb 100644
--- a/src/site/xdoc/contribute.xml
+++ b/src/site/xdoc/contribute.xml
@@ -253,13 +253,21 @@ Here is some more details about what my commit does, and the rationals of the ch
               <ol>Then we order by artifactId</ol>
               <ol>Then we order by type. <i>test-jar</i> goes last.</ol>
             </ul>
-            Hopefully, some tools are doing this sorting for you:</li>
+            Proper ordering is enforced by the project build. The build will fail in case violations are detected</li>
+          <li>POM files, as well as sections ordering should follows the <a href="http://maven.apache.org/ref/3.0.3/maven-model/maven.html">Maven Model</a></li>
         </ul>
+
+        You can quickly check the status of your pom files using:
+        <pre>
+          <code>mvn validate</code>
+        </pre>
+        You can ask the build to reorder pom files according to the rules using the <code>sortPom</code> profile:
         <pre>
-          <code>mvn com.github.ekryd.sortpom:sortpom-maven-plugin:sort -Dsort.keepBlankLines -Dsort.sortDependencies=groupId,artifactId -Dsort.nrOfIndentSpace=4 -Dsort.createBackupFile=false -Dsort.sortModules=true -Dsort.expandEmptyElements=false  -Dsort.predefinedSortOrder="recommended_2008_06"</code>
+          <code>mvn validate -PsortPom</code>
         </pre>
+        <p>Make sure you properly review all changes made by the automatic rewriting as XML processing tools are liberal
+        with whitespace.</p>
         <p>You should also split multiple attributes each on a new line.</p>
-        <p>You should ensure your POM files, as well as sections ordering follows the <a href="http://maven.apache.org/ref/3.0.3/maven-model/maven.html">Maven Model</a></p>
       </p>
       <p>
         <strong>Eclipse IDE</strong>


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org