Merge branch 'master' into issue-714

Author: bjornharrtell

.gitignore

@@ -1,11 +1,17 @@
 .idea
 *.iml
 target
+build
+
+# eclipse ignores
 .classpath
 .project
 .settings
 .externalToolBuilders
-build
+.checkstyle
+.eclipse-pmd
+.pmd
+.ruleset
 
 # standard ignores
 *.class
@@ -14,4 +20,7 @@ build
 hs_err_pid*
 
 # operating system specific
-.DS_Store
+.DS_Store
+
+# maven ignores
+pom.xml.versionsBackup

DEVELOPING.md

@@ -22,78 +22,153 @@ The JTS build chain uses Maven.  Build commands are executed at the project root
 
 * Build everything:
 
-        mvn install -Pall
+        mvn install -Dall=true
 
-## Javadoc
-
-* Build Javadoc for core modules
-
-        mvn javadoc:aggregate
-
-## Eclipse Configuration
-
-* Generate Eclipse configuration using `mvn eclipse:eclipse`
-* Import the generated projects into an Eclipse workspace
+* Limit build to release artifacts:
 
-### Run Configurations
+        mvn install -Drelease=true
 
-It is convenient to define the following Run Configurations:
+## Quality Assurance
 
+JTS build verify stage includes pmd, checkstyle and more:
 
-* **JTS TestRunner** - for executing XML tests:
+        mvn verify
 
-Field | Value
-------|------
-Type | Java Application
-Project | `jts-tests`
-Main class | `org.locationtech.jtstest.testrunner.JTSTestRunnerCmd`
-Program arguments | `validate general`
-Working directory | `${workspace_loc:jts-tests/src/test/resources/testxml}`
+To skip QA checks:
 
-* **JTS TestBuilder** - for viewing and processing geometry with JTS
+        mvn verify -Dpmd.skip=true -Dcheckstyle.skip=true
 
-Field | Value
-------|------
-Type | Java Application
-Project | `jts-app`
-Main class | `org.locationtech.jtstest.testbuilder.JTSTestBuilder`
-Program arguments (optional) | `-geomfunc <classname> ...`
-VM args | `-Xmx1000M`
-VM args (optional, for Mac) | `-Dswing.defaultlaf=javax.swing.plaf.metal.MetalLookAndFeel`
-Working directory | Default
+To browse QA errors:
+       
+        mvn site:site
+        open modules/core/target/site/index.html
 
-## Testing
+### JUnit tests
 
 JTS aims for 100% code coverage for unit tests.
+Unit tests are written in Java using JUnit.
+They are used for verifying API code, internal data structures, and ancillary algorithms.
 
-There are two kinds of unit tests:
-
-### JUnit tests
-
-Used for verifying API code, internal data structures, and ancillary algorithms.
-These tests are written in Java.
-This allows testing all parts of the codebase,
-and can provide richer error detection and reporting.
-However, the tests are not as readable or portable
-as the XML tests.
+This allows testing all parts of the codebase, and can provide richer error detection and reporting.
+However, the tests are not as readable or portable as the XML tests.
 
-* To run the unit tests in a module (`jts-core`):
+* Run the unit tests in a module (e.g. `jts-core`):
 
         mvn test -pl modules/core
 
 ### XML Tests
 
-JTS provides a code-independent, declarative XML-based format for expressing geometric functional tests.
+JTS provides a simple language-independent, declarative XML-based format for expressing geometric functional tests.
+
 This format has the following advantages:
 
-* allows encoding large geometries
-* provides geometric test cases in a reusable way
-* easily consumed by tools such as the JTS TestBuilder or by other geometry libraries (e.g. GEOS)
+* allows encoding large geometries more easily
+* provides geometric test cases in a reusable, language-independent way
+* easily consumed by tools such as the **JTS TestBuilder** 
+* easily used by JTS ports (e.g. [GEOS](https://trac.osgeo.org/geos)) or other geometry libraries 
 * allows geometric tests to be used with other operation implementations, for testing or comparison purposes
 
-This format should be used for tests which involve large geometries, or which
+This format should be used for tests which
 express fundamental geometric semantics of the JTS library.
 
-The XML test format can be executed using the JTS TestRunner, or imported into the JTS TestBuilder.
+The XML test format can be executed using the **JTS TestRunner**, or imported into the **JTS TestBuilder**.
+
+### External QA tools
 
+#### LGTM CodeQL analysis
+[![Total alerts](https://img.shields.io/lgtm/alerts/g/locationtech/jts.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/locationtech/jts/alerts/) 
+[![Language grade: Java](https://img.shields.io/lgtm/grade/java/g/locationtech/jts.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/locationtech/jts/context:java)
+* [Alerts report](https://lgtm.com/projects/g/locationtech/jts/alerts/?mode=tree)
+
+
+#### ABI Laboratory Tracker
+* [Binary compatibility report for JTS core](https://abi-laboratory.pro/?view=timeline&lang=java&l=jts-core)
+* [Binary compatibility for JTS 1.15 and before](https://abi-laboratory.pro/index.php?view=timeline&lang=java&l=jts)
+
+## Javadoc
+
+* Build Javadoc for core modules
+
+        mvn javadoc:aggregate
+
+## Eclipse Configuration
+
+Project:
+
+1. Startup eclipse, creating a new `jts-workspace` location. This folder is used by eclipse to keep track of settings alongside your jts source code.
+   
+2. Use *File > Import*, and the wizard *Maven > Existing Maven Project*.
+   
+   Select top-level `jts` folder as the Root directory.
+
+3. Once imported eclipse will build the project using built-in maven support.
+   
+4. During initial build warning is shown for maven lifecycle mapping for `checkstyle:check`. Use the quickfix to **ignore** this lifecycle mapping.
+   
+   Do not try the *maven-checkstyle-plugin* connector as it fails to install.
+
+Plugins:
+
+* Install *Eclipse-CS* from the market place.
+
+  1. Select *jts-core* project properties and navigate to *Checkstyle* preference page.
+
+  2. From the *Local check configuration* tab use *new* to create a check configuration.
+
+  3. Setup a *Project Relative Configuration* named `jts`, selecting ``build-tools/src/main/resources/jts/checkstyle.xml``
+     
+  4. Press *Additional properties* to open the *Additional Checkstyle configuration file properties* dialog.
+  
+  5. Press *Find unresolved properties* to define:
+     
+     * property `checkstyle.header.file` value: Absolute path to `src/main/resources/jts/header.txt`
+     * property `checkstyle.header.file`value: Absolute path to `src/main/resources/jts/suppressions.xml`
+
+  6. From the *Main* tab:
+     
+     * Enable *Checkstyle active for this project*.
+     * Select ``jts`` configuration
+     
+  7. You can *jts-core* as a blueprint to copy the Checkstyle configuration to other modules.
+  
+  Checkstyle is integrated into the build cycle updating warnings each time you save.
+
+* Install *eclipse-pmd* following directions for [offline install](https://acanda.github.io/eclipse-pmd/getting-started.html) to download a [recent release](https://github.com/eclipse-pmd/eclipse-pmd/releases/).
+  
+  1. Select *jts-core* project properties and navigate to *PMD* preference page.
+  2. Use *add* button to add a workspace ruleset using `build-tools/src/main/resources/jts/pmd-ruleset.xml`
+  3. Name the ruleset `jts`
+  
+  PMD is integrated into the build cycle updating warnings each time you save, and providing some quickfixes.
+
+* Alternative: Install *pmd-eclipse-plugin* from the market place.
+
+  1. Select *jts-core* project properties and navigate to *PMD* preference page.
+  2. Enable PMD
+  3. Use a the ruleset configured in a project file, selecting `build-tools/src/main/resources/jts/pmd-ruleset.xml`
+  
+  You can use *PMD > Check code* to list errors and warnings. The results are shown in their own view, and quickfixes are not available.
+  
+Run Configurations:
+
+* **JTS TestRunner** - for executing XML tests:
+
+  Field | Value
+  ------|------
+  Type | Java Application
+  Project | `jts-tests`
+  Main class | `org.locationtech.jtstest.testrunner.JTSTestRunnerCmd`
+  Program arguments | `validate general`
+  Working directory | `${workspace_loc:jts-tests/src/test/resources/testxml}`
+
+* **JTS TestBuilder** - for viewing and processing geometry with JTS
 
+  Field | Value
+  ------|------
+  Type | Java Application
+  Project | `jts-app`
+  Main class | `org.locationtech.jtstest.testbuilder.JTSTestBuilder`
+  Program arguments (optional) | `-geomfunc <classname> ...`
+  VM args | `-Xmx1000M`
+  VM args (optional, for Mac) | `-Dswing.defaultlaf=javax.swing.plaf.metal.MetalLookAndFeel`
+  Working directory | Default

README.md

@@ -32,6 +32,10 @@ Currently JTS targets Java 1.8 and above.
 * [Mailing List](https://accounts.eclipse.org/mailing-list/jts-dev)
 * [Gitter Channel](https://gitter.im/locationtech/jts)
 
+### Forums
+* [Stack Overflow](https://stackoverflow.com/questions/tagged/jts)
+* [GIS Stack Exchange](https://gis.stackexchange.com/questions/tagged/jts-topology-suite)
+
 ## License
 
 JTS is open source software.  It is dual-licensed under:
@@ -70,6 +74,7 @@ If you are interested in contributing to JTS please read the [**Contributing Gui
 * [**GEOS**](https://trac.osgeo.org/geos) - C++
 * [**NetTopologySuite**](https://github.com/NetTopologySuite/NetTopologySuite) - .NET
 * [**JSTS**](https://github.com/bjornharrtell/jsts) - JavaScript
+* [**dart_jts]([https://pub.dev/packages/dart_jts](https://github.com/moovida/dart_jts)) - Dart
 
 ### Via GEOS
 * [**Shapely**](https://github.com/Toblerity/Shapely) - Python wrapper of GEOS

RELEASING.md

@@ -58,20 +58,28 @@ On master:
 2. Update version number in Maven POMs (run the Maven release plugin at project root:
 
    ```
-   mvn versions:set -DnewVersion=1.18.0
+   mvn versions:set -DnewVersion=1.19.0
    ```
 
+3. Edit ``build-tools/pom.xml`` by hand, and compile to test.
+   
+   ```
+   mvn clean install
+   ```
+   
 3. Commit this change.
 
    ```
-   git commit -m "Release version 1.18.0"
+   git add .
+   git commit -m "Release version 1.19.0"
    git push
    ```
       
 4. Tag this commit, and push the tag to GitHub.
 
    ```
-   git tag -a 1.18.0 -m "Release version 1.18.0"
+   git tag -a 1.19.0 -m "Release version 1.19.0"
+   git push --tags
    ```
 
    This is the commit that will form the GitHub release below.
@@ -87,9 +95,8 @@ On master:
 
    To interact with the agent (so it asks you the passphrase):
 
-   ````
-   gpg --use-agent --armor --detach-sign --output $output pom.xml
-   rm pom.xml.asc
+   ```
+   gpg --use-agent --armor --detach-sign --output - pom.xml
    ```
 
    Reference: [Configuring GPG/PGP for Maven Releases to Sonatype on Mac OS X](https://nblair.github.io/2015/10/29/maven-gpg-sonatype/)
@@ -149,10 +156,33 @@ Update [Javadoc on JTS Github IO](http://locationtech.github.io/jts/javadoc/):
 
 2. Update branch [`gh-pages`](https://github.com/locationtech/jts/tree/gh-pages):
 
-   * clone
-   * branch
-   * copy new Javadoc
-   * commit
+   ```bash
+   cd ..
+   git clone https://github.com/locationtech/jts.git jts-docs
+   cd jts-docs
+   git checkout --track origin/gh-pages
+   git mv javadoc javadoc-1.18.0
+   git mv javadoc-io javadoc-io-1.18.0
+   cp -r ../jts/modules/core/target/apidocs/ javadoc  
+   cp -r ../jts/modules/io/common/target/apidocs javadoc-io
+   ```
+   
+   Edit ``index.html`` with new details:
+   
+   ```
+   <li>Javadoc for JTS 1.19.0 (
+       <a href="javadoc/index.html" target="javadoc">jts-core</a> |
+       <a href="javadoc-io/index.html" target="javadoc">jts-io-common</a>)</li>
+   <li>Javadoc for JTS 1.18.0 (
+       <a href="javadoc-1.18.0/index.html" target="javadoc">jts-core</a> |
+       <a href="javadoc-io-1.18.0/index.html" target="javadoc">jts-io-common</a>)</li>
+   ```
+   
+   Commit 
+   ```
+   git add .
+   git commit -m "JTS 1.19.0 javadocs"
+   ```
 
 ### Post release
 
@@ -164,7 +194,7 @@ Update master to the next release version:
 
    ```
    public static final int MAJOR = 1;
-   public static final int MINOR = 18;
+   public static final int MINOR = 19;
    public static final int PATCH = 0;
    private static final String RELEASE_INFO = "";
    ```
@@ -173,23 +203,31 @@ Update master to the next release version:
 
    ```
    public static final int MAJOR = 1;
-   public static final int MINOR = 19;
+   public static final int MINOR = 20;
    public static final int PATCH = 0;
    private static final String RELEASE_INFO = "SNAPSHOT";
    ```
 
 2. Update version number in Maven POMs (run the Maven release plugin at project root:
 
    ```
-   mvn versions:set -DnewVersion=1.19.0-SNAPSHOT
+   mvn versions:set -DnewVersion=1.20.0-SNAPSHOT
+   ```
+   
+3. Edit ``build-tools/pom.xml`` by hand, and compile to test.
+   
+   ```
+   mvn clean install
    ```
 
-3. Commit this change.
+3. Compile to test, and commit this change.
 
    ```
-   git commit -m "Version 1.19.0-SNAPSHOT"
+   git add .
+   git commit -m "Version 1.20.0-SNAPSHOT"
    git push
-   ```
+   ```  
+   
 4. Add a new version entry to the [Version History](https://github.com/locationtech/jts/blob/master/doc/JTS_Version_History.md)
 
 ### Announcing