The Spatial4j project is always excited to accept contributions from the community. This document contains some guidelines to help users and developers contribute to the project.
Spatial4j adheres to (as much as possible) the Google Java Style conventions. If a patch or commit deviates from these guidelines a reviewer will likely ask for it to be reformatted.
Spatial4j utilizes Github for issue tracking. Bugs, issues, and feature requests should be filed here.
Often communication can be carried out through comments on an issue or pull request directly but for larger discussions that are more general in nature it is recommended that the project mailing list be used.
The best way to submit a patch or add a new feature to the code is to submit a pull request. Below are some guidelines to follow when developing code intended to be submitted via pull request.
This guide contains some useful guidelines for contributing to open source projects in general. Below are some additionally stressed points.
It is never a bad idea to email the mailing list with thoughts about a change you intend to make before you make it. This allows the committers to weigh in with thoughts and suggestions that will help you make the change and ultimately ensure your successful contribution to the project.
Non-committers submitting patches to Spatial4j must use the "-s" (sign-off) flag when making commits with git. This flag indicates that the author verifies the change is (too the best knowledge of the author) in good standing and consistent with the open source license of the project, and that if he/she has permission from their employer to contribute the code (if applicable). The following is an example of a commit with the sign-off flag.
git commit -s -m "the commit message"
Once a developer has been elevated to project committer status the sign-off flag is no longer required.
Additionally, a one-time event is to submit a a CLA "Contributor License Agreement". It's simple and fast to do.
Avoid submitting patches that mix together multiple features and/or bug fixes into a single changeset. It is much easier to review and understand a patch that is dedicated to a single purpose.
While working on a patch often developers can't resist the urge to reformat code that is unrelated to the patch. This adds unnecessary "noise" that makes the job of the reviewer more difficult. It also makes the history of a change harder to analyze after the fact. If a patch contains unnecessary whitespace or other formatting changes a reviewer will ask for them to be removed.
(Optional) We recommended that developers do this step to be able to view the pre-LocationTech history of the project. This can be achieved with the following command after the repository has been cloned:
git fetch origin refs/replace/*:refs/replace/*