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 <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
