kemitix/kemitix-parent
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Rewrite README

Browse source
This commit is contained in:
Paul Campbell 2017-12-29 18:49:54 +00:00
parent c494866e16
commit b0e3f4c2af
1 changed files with 177 additions and 89 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

266
README.md
View file

@ -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
<project>
<parent>
<groupId>net.kemitix</groupId>
<artifactId>kemitix-parent</artifactId>
<version>RELEASE</version>
</parent>
```
## 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
<project>
<properties>
<tiles-maven-plugin.version>2.10</tiles-maven-plugin.version>
<kemitix-tiles.version>0.1.0-SNAPSHOT</kemitix-tiles.version>
</properties>
<build>
<plugins>
<plugin>
<groupId>io.repaint.maven</groupId>
<artifactId>tiles-maven-plugin</artifactId>
<version>${tiles-maven-plugin.version}</version>
<extensions>true</extensions>
<configuration>
<tiles>
<tile>net.kemitix.tiles:all-tiles:${kemitix-tiles.version}</tile>
<!-- or -->
<tile>net.kemitix.tiles:maven-plugins-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:enforcer-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:compiler-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:checkstyle-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:huntbugs-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:pmd-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:digraph-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:testing-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:coverage-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:pitest-tile:${kemitix-tiles.version}</tile>
<tile>net.kemitix.tiles:release-tile:${kemitix-tiles.version}</tile>
</tiles>
</configuration>
</plugin>
</plugins>
</build>
</project>
```
### 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.
`<properties>
<kemitix.build.directory>/mnt/ramdrive/${project.groupId}/${project.artifactId}</kemitix.build.directory>
</properties>`
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.