Refactor README (#53)

* Improve README

Author: jonathanaustin

README.md

@@ -1,17 +1,38 @@
 # java-common
 
-Reusable build configuration for BorderTech open source projects.
-
 ## Status
 [![Build Status](https://travis-ci.com/BorderTech/java-common.svg?branch=master)](https://travis-ci.com/BorderTech/java-common)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=bordertech-java-common&metric=alert_status)](https://sonarcloud.io/dashboard?id=bordertech-java-common)
 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=bordertech-java-common&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=bordertech-java-common)
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/c7a2226acd574943af9ae966c54b05e6)](https://app.codacy.com/app/BorderTech/java-common?utm_source=github.com&utm_medium=referral&utm_content=BorderTech/java-common&utm_campaign=Badge_Grade_Dashboard)
 [![Maven Central](https://img.shields.io/maven-central/v/com.github.bordertech.common/bordertech-parent.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.github.bordertech.common%22%20AND%20a:%22bordertech-parent%22)
 
-## qa-parent
+## Content
+
+- [What is java-common](#what-is-java-common)
+- [Why use java-common](#why-use-java-common)
+- [Getting started](#getting-started)
+- [Features](#features)
+- [Configuration](#configuration)
+- [Contributing](#contributing)
+
+## What is java-common
+
+Reusable build configuration and parent pom modules for BorderTech open source projects.
+
+## Why use java-common
+
+- Simplifies the steps to release your project to Maven Central
+- Enforce quality assurance and security checks on your project code
+
+## Getting started
 
-BorderTech java projects should generally use this as their parent POM.
+java-common provides two parent pom modules:
+
+- [bordertech-parent](https://github.com/BorderTech/java-common/blob/master/pom.xml) is the top level pom that configures [maven release plugin](https://maven.apache.org/maven-release/maven-release-plugin/)
+- [qa-parent](https://github.com/BorderTech/java-common/blob/master/qa-parent/pom.xml) provides quality assurance and security checks
+
+Projects should generally use qa-parent as their parent POM:
 
 ``` xml
 <project>
@@ -25,18 +46,48 @@ BorderTech java projects should generally use this as their parent POM.
 </project>
 ```
 
-It runs quality assurance checks on your java code using tools such as [Checkstyle](https://maven.apache.org/plugins/maven-checkstyle-plugin/checkstyle-mojo.html), [PMD](https://maven.apache.org/plugins/maven-pmd-plugin/) and [Spotbugs](https://spotbugs.github.io/spotbugs-maven-plugin/spotbugs-mojo.html).
-
-By default qa checks do not run, you must enable them on a per-module basis or parent pom like so:
+By default qa checks do not run, you must enable them on a per-module basis or in your project parent pom:
 
 ``` xml
-<properties>
-  <!-- Set bt.qa.skip to false to run QA checks. -->
+<property>
   <bt.qa.skip>false</bt.qa.skip>
-</properties>
+</property>
 ```
 
-Refer to qa-parent's [pom.xml](https://github.com/BorderTech/java-common/blob/master/qa-parent/pom.xml) for other project properties.
+### Releasing
+
+If using maven release ensure the necessary POM sections are overriden - these are marked in the bordertech-parent pom, for example:
+
+``` xml
+<!--
+  Descendants SHOULD override the url.
+-->
+<url>https://github.com/bordertech/java-common/</url>
+```
+
+Once you have configured your project and environment you can release to Maven Central.
+
+The golden rule for releasing is ALWAYS do the release on a separate branch (it makes [backing out](https://github.com/BorderTech/java-common/wiki/Releasing#dealing-with-failure) much easier when problems arise).
+
+Full documentation is available in the wiki under [Releasing](https://github.com/BorderTech/java-common/wiki/Releasing).
+
+## Features
+
+### bordertech-parent
+
+This is the top-level pom.xml file.
+
+It configures the [maven release plugin](https://maven.apache.org/maven-release/maven-release-plugin/index.html) for projects to release to Maven Central.
+
+_Note that java projects should generally not consume this directly but instead should use qa-parent as a parent POM instead._
+
+### qa-parent
+
+The qa-parent runs quality assurance checks on your java code using tools such as:
+
+- the [Checkstyle plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin) to check the code style used by the developers
+- the [PMD plugin](https://maven.apache.org/plugins/maven-pmd-plugin) for source code analysis
+- the [Spotbugs plugin](https://spotbugs.github.io/spotbugs-maven-plugin) that looks for bugs in Java programs using bug patterns
 
 The qa-parent also runs:
 
@@ -46,17 +97,19 @@ The qa-parent also runs:
 - the [JaCoCo plugin](https://www.eclemma.org/jacoco/trunk/doc/maven.html) for code coverage reports
 - the [Surefire plugin](https://maven.apache.org/surefire/maven-surefire-plugin) for running unit tests
 
-The qa-parent inherits all of the release functionality from bordertech-parent, discussed below.
+The qa-parent inherits all of the release functionality from bordertech-parent.
 
-## bordertech-parent
+### build-tools
 
-This is the top-level pom.xml file.
+This is primarily a shared resources module used by qa-parent and potentially other BorderTech maven modules.
 
-It configures the maven release plugin for open source BorderTech projects to release to Maven Central.
+## Configuration
 
-_Note that java projects should generally not consume this directly but instead should use qa-parent as a parent POM instead._
+### bordertech-parent config
 
-Projects using this must ensure the necessary POM sections are overriden - these are marked in the bordertech-parent pom, for example:
+Refer to bordertech-parent's [pom.xml](https://github.com/BorderTech/java-common/blob/master/pom.xml) for all project properties.
+
+Projects must ensure the necessary POM sections are overriden - these are marked in the bordertech-parent pom, for example:
 
 ``` xml
 <!--
@@ -65,56 +118,44 @@ Projects using this must ensure the necessary POM sections are overriden - these
 <url>https://github.com/bordertech/java-common/</url>
 ```
 
-Once you have configured your project and environment you can release to Maven Central. It may look a little something like the examples below.
-
-### Releasing
+### qa-parent config
 
-The golden rule is ALWAYS do the release on a separate branch (it makes [backing out](https://github.com/BorderTech/java-common/wiki/Releasing#dealing-with-failure) much easier when problems arise).
+Refer to qa-parent's [pom.xml](https://github.com/BorderTech/java-common/blob/master/qa-parent/pom.xml) for all project properties.
 
-Full documentation is available in the wiki under [Releasing](https://github.com/BorderTech/java-common/wiki/Releasing).
-
-## build-tools
-
-This is primarily a shared resources module used by qa-parent and potentially other BorderTech maven modules.
+Refer to the plugins used by qa-parent for all override details:
 
-## qa-parent overrides
-
-### Plugins used in QA Parent
-
-Refer to the plugins for all override details:
-
-- [Checkstyle plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/checkstyle-mojo.html)
-- [PMD plugin](https://maven.apache.org/plugins/maven-pmd-plugin/)
-- [Spotbugs plugin](https://spotbugs.github.io/spotbugs-maven-plugin/spotbugs-mojo.html)
-- [OWASP plugin](https://jeremylong.github.io/DependencyCheck/dependency-check-maven/index.html)
-- [Enforcer plugin](https://maven.apache.org/enforcer/maven-enforcer-plugin/enforce-mojo.html)
+- [Checkstyle plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin)
+- [PMD plugin](https://maven.apache.org/plugins/maven-pmd-plugin)
+- [Spotbugs plugin](https://spotbugs.github.io/spotbugs-maven-plugin)
+- [OWASP plugin](https://jeremylong.github.io/DependencyCheck/dependency-check-maven)
+- [Enforcer plugin](https://maven.apache.org/enforcer/maven-enforcer-plugin)
 - [Version checker plugin](https://www.mojohaus.org/versions-maven-plugin)
 - [JaCoCo plugin](https://www.eclemma.org/jacoco/trunk/doc/maven.html)
 - [Surefire plugin](https://maven.apache.org/surefire/maven-surefire-plugin)
 
-### Enable Static Analysis
+#### Enable Static Analysis
 
-By default qa checks do not run, you must enable them on a per-module basis or parent pom.
+By default qa checks (i.e. Checkstyle, PMD and Spotbugs) do not run, you must enable them on a per-module basis or the project parent pom:
 
 ``` xml
 <property>
   <bt.qa.skip>false</bt.qa.skip>
 </property>
 ```
 
-### Checkstyle
+#### Checkstyle
 
-Refer to [Checkstyle plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/checkstyle-mojo.html) for all override details.
+Refer to [Checkstyle plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin) for all override details.
 
-#### Skip Checkstyle
+##### Skip Checkstyle
 
 ``` xml
 <property>
   <checkstyle.skip>true</checkstyle.skip>
 </property>
 ```
 
-#### Change or Add Checkstyle Rules
+##### Change or Add Checkstyle Rules
 
 The checkstyle config defaults to `bordertech/bt-checkstyle.xml`. This config is based on `sun-checks.xml` provided by checkstyle.
 
@@ -126,7 +167,7 @@ To add or change a checkstyle rule you are required to create your own [config.x
 </property>
 ```
 
-#### Ignore Checkstyle Rule
+##### Ignore Checkstyle Rule
 
 Create a [suppression](http://checkstyle.sourceforge.net/config_filters.html) file add set the `checkstyle.suppressions.location` property.
 
@@ -147,11 +188,11 @@ Example suppression file:-
 </suppressions>
 ```
 
-### PMD and CPD
+#### PMD and CPD
 
-Refer to [PMD plugin](https://maven.apache.org/plugins/maven-pmd-plugin/) for all override details.
+Refer to [PMD plugin](https://maven.apache.org/plugins/maven-pmd-plugin) for all override details.
 
-#### Skip PMD and CPD
+##### Skip PMD and CPD
 
 ``` xml
 <property>
@@ -160,7 +201,7 @@ Refer to [PMD plugin](https://maven.apache.org/plugins/maven-pmd-plugin/) for al
 </property>
 ```
 
-#### Change PMD Rule Set
+##### Change PMD Rule Set
 
 The default rule set is `bordertech/bt-pmd-rules.xml`.
 
@@ -172,7 +213,7 @@ You can override the default by creating your own custom [rule set](https://pmd.
 </property>
 ```
 
-#### Add extra PMD Rule set
+##### Add extra PMD Rule set
 
 An extra [rule set](https://pmd.github.io/latest/pmd_userdocs_making_rulesets.html) can be added via the plugin `rulesets` configuration.
 
@@ -189,7 +230,7 @@ An extra [rule set](https://pmd.github.io/latest/pmd_userdocs_making_rulesets.ht
 </plugin>
 ```
 
-#### Ignore PMD Rule
+##### Ignore PMD Rule
 
 Create an [excludes](https://pmd.github.io/latest/pmd_userdocs_suppressing_warnings.html#xpath-and-regex-message-suppression) file that lists classes and rules to be excluded from failures and set the `pmd.excludeFromFailureFile` property.
 
@@ -205,19 +246,19 @@ Example properties file:
 com.my.example.MyClass=LoggerIsNotStaticFinal
 ```
 
-### Spotbugs
+#### Spotbugs
 
-Refer to [spotbugs plugin](https://spotbugs.github.io/spotbugs-maven-plugin/spotbugs-mojo.html) or [doco](https://spotbugs.readthedocs.io/en/latest/index.html) for all override details.
+Refer to [spotbugs plugin](https://spotbugs.github.io/spotbugs-maven-plugin) or [doco](https://spotbugs.readthedocs.io/en/latest/index.html) for all override details.
 
-#### Skip spotbugs
+##### Skip spotbugs
 
 ``` xml
 <property>
   <spotbugs.skip>true</spotbugs.skip>
 </property>
 ```
 
-#### Ignore Spotbugs Rule
+##### Ignore Spotbugs Rule
 
 Create a [filter](https://spotbugs.readthedocs.io/en/latest/filter.html) file and set `spotbugs.excludeFilterFile` property.
 
@@ -240,19 +281,19 @@ Example filter file:-
 </FindBugsFilter>
 ```
 
-### OWASP
+#### OWASP
 
-Refer to [OWASP plugin](https://jeremylong.github.io/DependencyCheck/dependency-check-maven/index.html) for all override details.
+Refer to [OWASP plugin](https://jeremylong.github.io/DependencyCheck/dependency-check-maven) for all override details.
 
-#### Skip OWASP
+##### Skip OWASP
 
 ``` xml
 <property>
   <dependency-check.skip>true</dependency-check.skip>
 </property>
 ```
 
-#### Ignore OWASP Rule
+##### Ignore OWASP Rule
 
 Create a [suppression](https://jeremylong.github.io/DependencyCheck/general/suppression.html) file add set the `suppression.file` property.
 
@@ -262,7 +303,7 @@ Create a [suppression](https://jeremylong.github.io/DependencyCheck/general/supp
 </property>
 ```
 
-#### Using OWASP behind a Proxy
+##### Using OWASP behind a Proxy
 
 If you are behind a Proxy then the OWASP plugin needs to be told which proxy to use. You can set the `mavenSettingsProxyId` property in your settings.xml to the appropriate PROXY-ID (which is usually defined in the same settings.xml).
 
@@ -274,29 +315,31 @@ If you are behind a Proxy then the OWASP plugin needs to be told which proxy to
 
 Updating the OWASP vulnerability database can also be blocked by the PROXY blocking HTTP HEAD requests. To work around this you will need a command line option: `-Ddownloader.quick.query.timestamp=false`
 
-### Enforcer Plugin
+#### Enforcer Plugin
 
-Refer to [enforcer plugin](https://maven.apache.org/enforcer/maven-enforcer-plugin/enforce-mojo.html) for all override details.
+Refer to [enforcer plugin](https://maven.apache.org/enforcer/maven-enforcer-plugin) for all override details.
 
-#### Skip enforcer
+##### Skip enforcer
 
 ``` xml
 <property>
   <enforcer.skip>true</enforcer.skip>
 </property>
 ```
 
-#### Report issues but dont fail
+##### Report issues but dont fail
 
 ``` xml
 <property>
   <enforcer.fail>false</enforcer.fail>
 </property>
 ```
 
-### Build tools module for override artefacts
+#### Build tools module for override artefacts
 
-If your project has multiple modules and you want to provide the same override/exclude files for all the submodules, then a good solution is to use a `build-tools` module similar to [java-common/build-tools](https://github.com/BorderTech/java-common/tree/master/build-tools). Define a `build-tools` submodule that holds the override/exclude files and then define the plugins you want to override in the project parent pom with the custom build-tools module as a dependency.
+If your project has multiple modules and you want to provide the same override/exclude files for all the submodules, then a good solution is to use a `build-tools` module similar to [java-common/build-tools](https://github.com/BorderTech/java-common/tree/master/build-tools).
+
+Once you have created a build-tools submodule, define the plugins you want to override in the project parent pom with the custom build-tools module as a dependency.
 
 ``` xml
 <!-- Example of adding a custom build-tools module to spotbugs -->
@@ -313,3 +356,7 @@ If your project has multiple modules and you want to provide the same override/e
   </dependencies>
 </plugin>
 ```
+
+## Contributing
+
+Refer to these guidelines for [Workflow](https://github.com/BorderTech/java-common/wiki/Workflow) and [Releasing](https://github.com/BorderTech/java-common/wiki/Releasing).