kopia lustrzana https://github.com/onthegomap/planetiler
97 wiersze
5.0 KiB
Markdown
97 wiersze
5.0 KiB
Markdown
# 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](planetiler-core/src/test/java/com/onthegomap/planetiler/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](README.md#git-submodules)
|
|
- Install Java 21 or later. You can download Java manually from [Adoptium](https://adoptium.net/installation.html) or
|
|
use:
|
|
- [Windows installer](https://adoptium.net/installation.html#windows-msi)
|
|
- [macOS installer](https://adoptium.net/installation.html#macos-pkg) (or `brew install --cask temurin`,
|
|
or `port install openjdk21-temurin`)
|
|
- [Linux installer](https://adoptium.net/installation/linux/) (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](https://github.com/takari/maven-wrapper) 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`:
|
|
|
|
```sh
|
|
./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](https://www.jetbrains.com/help/idea/installation-guide.html)
|
|
- Install
|
|
the [Adapter for Eclipse Code Formatter plugin](https://plugins.jetbrains.com/plugin/6546-adapter-for-eclipse-code-formatter)
|
|
- 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](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack)
|
|
- 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](https://code.visualstudio.com/docs/languages/java).
|
|
|
|
### Eclipse
|
|
|
|
- In [Eclipse for Java Developers](https://www.eclipse.org/downloads/packages/), 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`](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](https://sonarcloud.io/project/overview?id=onthegomap_planetiler) 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](https://www.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`
|
|
|