diff --git a/README.md b/README.md index 5721f4d..bf92baf 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,129 @@ KEMITIX-PARENT ============== -This Maven Parent POM several preconfigured plugins. +* `kemitix-parent` +* `kemitix-maven-tiles` + +## Parent + +A parent POM for my own personal projects. ### Usage -#### Maven - +```xml + net.kemitix kemitix-parent RELEASE +``` -## Versions +### Contents -If you want to override the version or configuration values of any of the -plugins configured by this parent, you can set the following properties to the -desired value. +The POM defines the following items: -* project.build.sourceEncoding -* project.reporting.outputEncoding -* kemitix.build.directory -* kemitix-quality-maven-plugin.version -* lombok.version -* maven-javadoc-plugin.version -* maven-source-plugin.version -* maven-gpg-plugin.version -* maven-deploy-plugin.version -* maven-compiler-plugin.version -* maven-surefire-plugin.version -* maven-failsafe-plugin.version -* maven-jxr-plugin.version -* java.version -* versions.version -* coveralls-maven-plugin.version +* `issueManagement` +* `scm` +* `url` +* `inceptionYear` +* `licenses` +* `developers` +* `distributionManagement` -## Kemitix Quality +The POM sets the following properties: -The [kemitix-quality-maven-plugin](https://github.com/kemitix/kemitix-quality-maven-plugin) -provides several preconfigured quality related plugins. +* `project.reporting.outputEncoding` as `UTF-8` +* `java.version` as `1.8` -N.B. The Kemitix Quality plugin required 100% code instruction coverage and mutation ratio. See the project page for details of adjusting these levels if needed. +## Tiles -## Maven Compiler Plugin +Maven Tiles for preconfigured plugins. These can be used independently of the `kemitix-parent` POM. -The [Maven Compiler Plugin](https://maven.apache.org/plugins/maven-compiler-plugin/) -compiles your sources. +### Usage -### Configuration +```xml + + + 2.10 + 0.1.0-SNAPSHOT + + + + + io.repaint.maven + tiles-maven-plugin + ${tiles-maven-plugin.version} + true + + + net.kemitix.tiles:all-tiles:${kemitix-tiles.version} + + + + net.kemitix.tiles:maven-plugins-tile:${kemitix-tiles.version} + net.kemitix.tiles:enforcer-tile:${kemitix-tiles.version} + net.kemitix.tiles:compiler-tile:${kemitix-tiles.version} + net.kemitix.tiles:checkstyle-tile:${kemitix-tiles.version} + net.kemitix.tiles:huntbugs-tile:${kemitix-tiles.version} + net.kemitix.tiles:pmd-tile:${kemitix-tiles.version} + net.kemitix.tiles:digraph-tile:${kemitix-tiles.version} + net.kemitix.tiles:testing-tile:${kemitix-tiles.version} + net.kemitix.tiles:coverage-tile:${kemitix-tiles.version} + net.kemitix.tiles:pitest-tile:${kemitix-tiles.version} + net.kemitix.tiles:release-tile:${kemitix-tiles.version} + + + + + + +``` + +### Properties + +If you want to override the version or configuration values of any of the plugins configured by the tiles, you can set the following properties to the desired value. + +* `project.build.sourceEncoding` +* `maven-javadoc-plugin.version` +* `maven-source-plugin.version` +* `maven-gpg-plugin.version` +* `maven-deploy-plugin.version` +* `maven-compiler-plugin.version` +* `maven-surefire-plugin.version` +* `maven-failsafe-plugin.version` +* `maven-jxr-plugin.version` +* `java.version` +* `versions.version` +* `coveralls-maven-plugin.version` + +### Maven Plugins Tile + +Sets updated versions for the following `org.apache.maven.plugins`: + +* `maven-clean-plugin` +* `maven-install-plugin` +* `maven-site-plugin` + +Adds an updated version of the `org.codehaus.mojo:versions-maven-plugin` plugin. + +#### Maven JXR Plugin + +The [Maven JXR Plugin](http://maven.apache.org/jxr/maven-jxr-plugin/index.html) produces cross-referenced HTML pages of your source code as part of the `compile` phase in `target/site/xref/`. + +### Enforcer Tile + +Provides the `maven-enforcer-plugin`, performing the `display-info` and `enforce` goals during the `validate` phase. + +Required Maven Version is set by the `required-maven.version` property. + +Required Java Version is set by the `java.version` property. + +### Compiler Tile + +#### Maven Compiler Plugin + +The [Maven Compiler Plugin](https://maven.apache.org/plugins/maven-compiler-plugin/) compiles your sources. Ref: [compile:compile](https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html) @@ -58,101 +133,114 @@ Ref: [compile:compile](https://maven.apache.org/plugins/maven-compiler-plugin/co * target: ${java.version} * encoding: ${project.build.sourceEncoding} -## Maven Surefire Plugin +### Checkstyle Tile -The [Maven Surefire Plugin](http://maven.apache.org/surefire/maven-surefire-plugin/index.html) -runs your Unit Tests. +The [Maven Checkstyle Plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/) verifies the source code against a Checkstyle ruleset file. -### Configuration +The default ruleset is the level `5-complexity` ruleset from [`kemitix-checkstyle-ruleset`](https://github.com/kemitix/kemitix-checkstyle-ruleset). -No configuration applied beyond the defaults. +To use another level within `kemitix-checkstyle-ruleset`, set the `ruleset.level` property. e.g. `4-tweaks`. -## Maven Failsafe Plugin +To use a different checkstyle ruleset completely, set the `checkstyle.ruleset.location` property. -The [Maven Failsafe Plugin](http://maven.apache.org/surefire/maven-failsafe-plugin/index.html) -runs your Integration Tests. -Runs its [integration-test](http://maven.apache.org/surefire/maven-failsafe-plugin/integration-test-mojo.html) -goal during the `verify` phase. +### Huntbugs Tile -### Configuration +The [Huntbugs Maven Plugin](https://github.com/amaembo/huntbugs) performs a static analysis of the compiled bytecode for common bug patterns during the `verify` phase. -No configuration applied beyond the defaults. +### PMD Tile -## Maven Source Plugin +The [PMD Maven Plugin](https://maven.apache.org/plugins/maven-pmd-plugin/) performs the PMD static code analysis during the `verify` phase. -The [Maven Source Plugin](https://maven.apache.org/plugins/maven-source-plugin/) -bundles your sources into a jar file ready for deployment. +Has a transitive dependency upon the `maven-plugins-tile` and includes it automatically. -Runs its [jar-no-fork](https://maven.apache.org/plugins/maven-source-plugin/jar-no-fork-mojo.html) -goal during the `verify` phase. +### Digraph Tile -### Configuration +The [Digraph Maven Plugin](https://github.com/kemitix/digraph-dependency-maven-plugin/) creates a graphviz diagram of the package dependencies within the source code during the `verify` phase. -No configuration applied beyond the defaults. +Set the property `digraph-dependency.basePackage` to the base of the project to be graphed. The default value is `net.kemitix`. -## Maven Javadoc Plugin +### Testing Tile -The [Maven Javadoc Plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/) -generates your html javadocs and bundles them into a jar file ready for -deployment. +#### Maven Surefire Plugin -Runs its [jar](https://maven.apache.org/plugins/maven-javadoc-plugin/jar-mojo.html) -goal during the `verify` phase. +The [Maven Surefire Plugin](http://maven.apache.org/surefire/maven-surefire-plugin/index.html) runs your Unit Tests during the `test` phase. -### Configuration +### Maven Failsafe Plugin -No configuration applied beyond the defaults. +The [Maven Failsafe Plugin](http://maven.apache.org/surefire/maven-failsafe-plugin/index.html) runs your Integration Tests during the `verify` phase. -## Maven Deploy Plugin +### Coverage Tile -The [Maven Deploy Plugin](https://maven.apache.org/plugins/maven-deploy-plugin/) -uploads your artifacts to a remote repository. +#### Jacoco -### Configuration +The [Jacoco Maven Plugin](http://www.eclemma.org/jacoco/trunk/doc/maven.html) verifies that the test suite meets the required coverage ratios. -No configuration applied beyond the defaults. +The defaults require that all classes, lines and branches be covered by tests. i.e. 100% code coverage. -## Maven JXR Plugin +Set the following properties to set less strict targets: -The [Maven JXR Plugin](http://maven.apache.org/jxr/maven-jxr-plugin/index.html) -produces cross-referenced HTML pages of your source code. +* `jacoco-class-line-covered-ratio` - default = 1 (i.e. 100%) +* `jacoco-class-instruction-covered-ratio` - default = 1 (i.e. 100%) +* `jacoco-class-missed-count-maximum` - default = 0 (i.e. #classes with no tests <= 0) -### Configuration +Classes with names that end in the following are excluded from these limits: -No configuration applied beyond the defaults. +* `Test` +* `IT` +* `Main` +* `Application` +* `Configuration` +* `Immutable` -## Coveralls +#### Coveralls -The [Coveralls Maven Plugin](https://github.com/trautonen/coveralls-maven-plugin) -publishes coverage data to coveralls.io. +The [Coveralls Maven Plugin](https://github.com/trautonen/coveralls-maven-plugin) publishes coverage data to coveralls.io. -### Configuration - -The plugin is not configured to run automatically. It must be initiated manually: +The plugin is not configured to run automatically. It must be initiated manually, and requires the `release` profile to be enabled: ```shell mvn -P release test jacoco:report coveralls:report ``` -#### Requirements +This runs the tests, creates the jacoco report from the tests then uploads the results to http://coveralls.io. -In order to use the plugin: +### Pitest Tile -* *must* enable the `release` profile +#### Mutation Testing -# Distribution Management +The [Pitest Maven Plugin](http://pitest.org/quickstart/maven/) perform mutation test coverage checks during the `verify` phase. -Remote repositories are provided for the Sonatype Nexus Snapshots and Nexus Release -Repositories. See the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) -for information on how to deploy your artifact the Maven Central through -Sonatype. +Code coverage must by 100% and all mutations must result in a test from the test suite failing. -### Changing the Build Directory +Set `pitest.skip` to avoid running the mutation test. -If you want to change the build directory, e.g. from your settings.xml to an SSD -or ram drive, then set the value of the `kemitix.build.directory` to your required -locations. e.g. -` -/mnt/ramdrive/${project.groupId}/${project.artifactId} -` +Set `pitest.coverage` to a value between 0 and 1 to set the allowed ratio of uncovered code. i.e. 0 = 100% code coverage, 0.2 = 80% code coverage + +Set `pitest.mutation` to a value between 0 and 1 to set the allowed mutations to survive the test suite. i.e. 0 = 100% mutations caught, 0.2 = 80% mutations caught + +#### Highwheel Cyclic Analysis + +The [Highwheel Maven Plugin](https://github.com/hcoles/highwheel) detects and visualises class and package cyclic dependencies during the `verify` phase. It also reports on tests that appear to have been orphaned during refactoring. + +The generated report is created in `target/highwheel/`. + +### Release Tile + +The plugins in this Tile are only activated when the `release` profile is enabled. + +#### Maven Source Plugin + +The [Maven Source Plugin](https://maven.apache.org/plugins/maven-source-plugin/) bundles your sources into a jar file ready for deployment. + +Runs its [jar-no-fork](https://maven.apache.org/plugins/maven-source-plugin/jar-no-fork-mojo.html) goal during the `verify` phase. + +#### Maven Javadoc Plugin + +The [Maven Javadoc Plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/) generates your html javadocs and bundles them into a jar file ready for deployment. + +Runs its [jar](https://maven.apache.org/plugins/maven-javadoc-plugin/jar-mojo.html) goal during the `verify` phase. + +#### Maven Deploy Plugin + +The [Maven Deploy Plugin](https://maven.apache.org/plugins/maven-deploy-plugin/) uploads your artifacts to a remote repository.