Skip to content

Latest commit

 

History

History
89 lines (60 loc) · 4.44 KB

CONTRIBUTE.md

File metadata and controls

89 lines (60 loc) · 4.44 KB
Raw

Contribution Guidelines

Firstly, thanks for using the ORS and contributing to making it better for everyone.

OpenRouteService has been around for over ten years, and as such it has seen many changes and adoption of new methodologies and techniques, as well as the coming and going of multiple developers. To try and keep the OpenRouteService codebase clean and stable, there are a few guidelines that we try to follow.

Issues

We accept technical issues, routing issues and feature requests. Common questions should be asked at ask.openrouteservice.org.

Please search for issues before creating a new one.

Technical issues

If you encounter a bug, please make sure to be as descriptive as possible, i.e.:

  • operating system (in case of self-hosting)
  • request URL (incl. parameters if POST)
  • expected outcome
  • actual outcome (e.g. JSON output)
  • fenced code around the bug, if known

Routing issues

If you encounter weird or unexpected behavior during routing, please make sure to rule out expected behavior based on road attributes from e.g. openstreetmap.org, such as unexpected one-way streets or access restrictions. Find an overview of our tagging filters for all transportation profiles in our backend documentation.

Information to include:

  • request URL (incl. parameters if POST)
  • expected outcome
  • actual outcome (e.g. JSON output)
  • screenshots where applicable (e.g. from our maps)

Feature requests

Here you can be creative, but still descriptive. Make sure to describe the current behavior, your desired behavior and to give actual use cases. That makes it whole easier for us to prioritize.

Pull Requests

We ❤️ pull requests! We also aspire to make our commit history cleaner and more sustainable, benefiting our contributors and us maintainers.

Pull request guidelines

We'd like all pull requests to adhere to the following rules:

  • a PR has to close an issue. If there is none yet for yours, please create one
  • branch off master
  • name your branch according to <[hotfix/bugfix/feat/algo]>/<issue#>-<purpose>, e.g. feat/#381-simplify_geometry
  • if you introduce new functions/classes, write unit or API tests
  • limit the number of commits to a minimum, i.e. use git commit --amend [--no-edit]
  • use meaningful commit messages, e.g. commit -m "Include geometry_simplify in API and core code"
  • if your branch needs an update from its base branch, use rebase, e.g.
git checkout my-new-feat
git stash
git rebase master
git stash pop

Be extra careful using rebase commands when collaborating on a branch with other people.

Don't merge master branch into your feature branch.

Contributing code

For a short explanation on how to setup, deploy and test openrouteservice locally for development, see our installation instructions.

Though there are no concrete rules for code that is contributed, we have a few general styles that should be adopted:

  • Descriptive names for variables, methods and classes
  • Minimal in-line comments: code should be self-explanatory. Never use comments to comment out blocks of code
  • Use JDoc docstrings to provide context for methods and classes
  • Unit tests!!
  • API test when adding API functionality in the corresponding openrouteservice-api-tests subproject
  • Keep methods modular: rather short and singular functionality than 100s line of code