planetiler/CONTRIBUTING.md

Contributing to Planetiler

Pull requests are welcome! Any pull request should:

• Include at least one unit test to verify the change in behavior
• Include an end-to-end test in PlanetilerTests.java to verify any major new user-facing features work
• Format the change ./mvnw spotless:apply and test with ./mvnw verify before pushing

To set up your local development environment:

• Fork the repo setup submodules
• Install Java 21 or later. You can download Java manually from Adoptium or use:
  • Windows installer
  • macOS installer (or brew install --cask temurin, or port install openjdk21-temurin)
  • Linux installer (or apt-get install openjdk-21-jdk)
  • If you update from an older version of java on Ubuntu, run sudo update-alternatives --config java after installing the new jdk.
• Build and run the tests (mvnw automatically downloads maven the first time you run it):

  • on mac/linux: ./mvnw clean test

  • on windows: mvnw.cmd clean test

  • or if you already have maven installed globally on your machine: mvn clean test

  • to run just one test e.g. GeoUtilsTest: ./mvnw -pl planetiler-core -Dtest=GeoUtilsTest test

  • to run benchmarks e.g. BenchmarkTileCoord:

    ./scripts/build.sh
    java -cp planetiler-dist/target/planetiler-dist-*-with-deps.jar com.onthegomap.planetiler.benchmarks.BenchmarkTileCoord
    

GitHub Workflows will run regression tests on any pull request.

IDE Setup

You can use any text editor as long as you format the code and test before pushing. A good IDE will make things a lot easier though.

IntelliJ IDEA (recommended)

• Install IntelliJ IDEA
• Install the Adapter for Eclipse Code Formatter plugin
• In IntelliJ, click Open, navigate to the the pom.xml file in the local copy of this repo, and Open then Open as Project
  • If IntelliJ asks (and you trust the code) then click Trust Project
• Under Preferences -> Tools -> Actions on Save (or File -> Settings -> Tools -> Actions on Save on Linux) select Reformat code and Optimize imports to automatically format code on save.
• To verify everything works correctly, right click on planetiler-core/src/test/java folder and click Run 'All Tests'

Troubleshooting:

• If any java source files show "Cannot resolve symbol..." errors for Planetiler classes, you might need to select: File -> Invalidate Caches... -> Just Restart.
• If you see a "Project JDK is not defined" error, then choose Setup SDK and point IntelliJ at the Java 21 or later installed on your system

Visual Studio Code

• Install the Extension Pack for Java
• In VSCode, click File -> Open and navigate to Planetiler directory
  • If VSCode asks (and you trust the code) then click Yes I trust the authors
• To verify everything works correctly, go to the Testing tab and click Run Tests

Learn more about using VSCode with Java here.

Eclipse

• In Eclipse for Java Developers, click File -> Import ... then Maven -> Existing Maven Projects, navigate to Planetiler directory, and click Finish
• Under Eclipse -> Preferences...:
  • Under Java -> Code Style -> Formatter and choose Import... choose eclipse-formatter.xml from the root of this project. Then choose Planetiler as the Active profile.
  • Under Java -> Editor -> Save Actions check Perform selected actions on save, Format source code , Format all lines and Organize imports
  • Under Java -> Code Style -> Organize Imports change the number of static imports needed for .* to 5, then remove the groups and add 2 new groups:
    • New Static... and *
    • New... and *
• To verify everything works correctly, right click on planetiler-core/src/test/java folder and click Run As -> JUnit Test

SonarLint Plugin Setup (optional, but recommended)

Planetiler uses SonarCloud to statically analyze pull requests to catch common bugs and security vulnerabilities. To preview Sonar warnings in VS Code, IntelliJ, or Eclipse:

• Follow the directions on sonarlint.org to install the plugin for your IDE
• Then to synchronize your local configuration with the one used in SonarCloud, enable connected mode for your IDE using "SonarCloud" connection type and the shared read-only API token used in GitHub CI: c2cfe8bd7368ced07e84a620b7c2487846e220eb