JarCastingcore-poms
Fundamental POMs for Gryphon Zone projects:
- base-pom - Parent POM for all Gryphon Zone projects
- base-bom - Managed versions of commonly used dependencies
Usage
base-pom
base-pom is meant to be used as a parent POM:
<parent>
<groupId>zone.gryphon</groupId>
<artifactId>base-pom</artifactId>
<version>VERSION</version>
</parent>
base-bom
base-bom should be included in the dependencyManagement section of the POM with the import scope, so that it will manage versions of project dependencies:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>zone.gryphon</groupId>
<artifactId>base-bom</artifactId>
<version>${base-bom.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Note that the property base-bom.version is defined in base-pom, so it does not need to be redefined.
Behavior
base-pom enables a number of default configurations based on Gryphon Zone best-practices. In the event the defaults are not acceptable for a child project, most of the executions can be configured via properties in the POM.
Bytecode Version
By default, Java 8 bytecode will be generated.
This can be changed using the java.version.minor property, e.g. to generate Java 7 bytecode set it to 7, for Java 8 set it to 8, etc...
POM Hygiene
POM Hygiene - Style
For POM hygiene, the sortpom-maven-plugin is enabled by default.
To exclude a section of the POM from being sorted, use the tags <?SORTPOM IGNORE?> and <?SORTPOM RESUME?>.
To disable POM sorting entirely, set the property sortpom.skip to true.
POM Hygiene - Dependencies
The analyze-only goal of the maven-dependency-plugin is used to detect dependency issues in the POM.
In the case of false positives, use the ignoredUnusedDeclaredDependencies configuration option to mark dependencies as used.
To prevent detected issues from failing the build, set dependency.fail.on.warnings to false.
Code Hygiene
Code Hygiene - Style
Gryphon Zone projects follow the Google Java Style Guide, with the following changes:
- Indentation is done with
4spaces, not2 - Line length/column limit is not limited to 100 characters
- Although not restricted, use best judgement as to when lines should wrap
This standard is enforced with the maven-checkstyle-plugin.
To temporarily prevent checkstyle failures from failing the build, set the property checkstyle.failOnViolation to false.
Code Hygiene - Bugs
Error Prone is enabled by default during compilation.
Code Hygiene - Test Coverage
JaCoCo is enabled by default for code coverage.
Github Pages
Autogenerated documentation can be published to the project's github-pages site during the site-deploy execution phase.
Step 1 - create gh-pages branch
The gh-pages branch must be created manually:
git checkout --orphan gh-pages
rm .git/index
git clean -fdx
touch .gitkeep
git add .gitkeep
git commit -m 'Create gh-pages branch'
git push --set-upstream origin gh-pages
For details on this step, refer to the maven-scm-publish-plugin
Step 2 - enable site generation
Enable generation of the Maven site by adding a src/site/site.xml file.
A minimal version of this file is:
<?xml version="1.0" encoding="UTF-8"?>
<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" name="${project.artifactId}">
</project>
Step 3 - enable site publication
Depending on whether the module is the root module or a child module, add one of the following files:
- root -
src/site/.gh-pages - child -
src/site/.gh-pages-child-module
e.g:
project-root
├── pom.xml
├── src
│ └── site
│ ├── site.xml
│ └── .gh-pages
│
├── child-module-one
│ ├── pom.xml
│ └── src
│ └── site
│ ├── site.xml
│ └── .gh-pages-child-module
│
└── child-module-two
├── pom.xml
└── src
└── site
├── site.xml
└── .gh-pages-child-module
note: this step is necessary because the maven-scm-publish-plugin is intended to be run as a aggregator plugin, and Maven lacks support for properly running Aggregator plugins which are defined in the POM, a problem which has been present for over ten years without a solution.
Note that currently grandchild modules are unsupported, e.g:
project-root
├── pom.xml
|
└── child-module
├── pom.xml
│
└── grandchild-module
├── pom.xml
└── src
└── site
└── site.xml
