planetiler/CONTRIBUTING.md

4.9 KiB

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:
  • 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.

  • 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

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