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, not 2
• 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