Skip to content

Refactor README #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jul 12, 2019
Merged

Refactor README #53

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fdf55b9
Improve README
jonathanaustin Jul 12, 2019
ffcbf28
Update README
jonathanaustin Jul 12, 2019
a4676f7
Update README
jonathanaustin Jul 12, 2019
2e345bb
Update README
jonathanaustin Jul 12, 2019
b62b261
Update README
jonathanaustin Jul 12, 2019
d1eea52
Update README
jonathanaustin Jul 12, 2019
4b82b17
Update README
jonathanaustin Jul 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 112 additions & 65 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
Expand All @@ -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:

Expand All @@ -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
<!--
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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>
Expand All @@ -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`.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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).

Expand All @@ -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 -->
Expand All @@ -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).