core-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
4
spaces, 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