Skip to content

Latest commit

 

History

History
117 lines (83 loc) · 5.18 KB

CONTRIBUTING.md

File metadata and controls

117 lines (83 loc) · 5.18 KB
Raw

Contribution Guidelines

Thanks for considering to make a contribution to the vast landscape of routing engine APIs. We'd be really happy to eventually be able to cover all remote routing API's, but have to rely on community contributions as this is a big task.

Table of Contents

Issues

  • Please only submit actual technical issues and use Stack Overflow for questions using the tag routingpy.

  • Please make sure you don't submit a duplicate by browsing open and closed issues first and consult the CHANGELOG for already fixed issues

Submitting fixes

We welcome patches and fixes to existing clients and want to make sure everything goes smoothly for you while submitting a PR.

We use the PSF's black to make sure the code style is consistent, and flake8 as a linter.

When contributing, we expect you to:

  • close an existing issue. If there is none yet for your fix, please create one.
  • write/adapt unit tests and/or mock API tests, depending on the introduced or fixed functionality
  • limit the number of commits to a minimum, i.e. responsible use of git commit --amend [--no-edit]
  • use meaningful commit messages, e.g. commit -m "[bugfix] heremaps used [lat, long] as locations input parameter"
  • you can branch off master and put a PR against master as well

Setup

  1. Create and activate a new virtual environment

  2. Install development dependencies:

# From the root of your git project
pip install -r requirements_dev.txt
# or
poetry install
  1. Run tests to check if all goes well:
# From the root of your git project
nosetests -v
  1. Please install the pre-commit hook, so your code gets auto-formatted and linted before committing it:
# From the root of your git project
pre-commit install

Tests

We only do mocked tests as routing results heavily depend on underlying data, which, at least in the case of the FOSS routing engines, changes on a very regular basis due to OpenStreetMap updates. All queries and most mocked responses are located in test/test_helper.py in dicts. This unfortunately also means, that our tests are less API tests and more unit tests and can't catch updates on providers' API changes.

Run nosetests with a coverage flag, which shouldn't report < 90% coverage overall (the starting point at the beginning of the project). A coveralls.io instance will check for coverage when you submit a PR.

# From the root of your git project
nosetests  --with-coverage --cover-package=routingpy

Documentation

If you add or remove new functionality which is exposed to the user/developer, please make sure to document these in the docstrings. To build the documentation:

# From the root of your git project
cd docs
make hmtl

The documentation will have been added to routingpy/docs/build/html and you can open index.html in your web browser to view the changes.

We realize that re-structured text is not the most user-friendly format, but it is the currently best available documentation format for Python projects. You'll find lots of copy/paste material in the existing implementations.

Adding router

Let's add all routers in the world:)

It's really easy:

  1. New class Create a new router module in routingpy/routers and base the new class on routingpy/routers/base.py:Router. Also, check if the service hasn't been added before. E.g. if the router you want to add is based on GraphHopper, you probably want to subclass routingpy/routers/graphhopper.py:Graphhopper class. Additionally, import the new router class in routingpy/routers/init.py.

  2. Implementations Implement the services the routing engine has to offer. The bare minimum is implementing the directions method. If the routing engine also offers isochrones and matrix, we'd require you to add those too. If you want to add an endpoint that doesn't exist yet in routingpy/routers/base.py:Router, please consult us first, as we need to make sure to be similarly consistent across different routing engines as we are with the existing endpoints.

  3. Tests Create a new test module testing the functionality, not the API. Use @responses.activate decorators for this. To run the new tests and ensure consistency, refer to the Tests section above. Don't store secrets in the tests.

  4. Document Please use docstring documentation for all user-exposed functionality, similar to other router implementations. Also, please register the new module in docs/indes.rst's Routers section. To build the docs, refer to the documentation section for details. Don't forget to add your name to the list of AUTHORS.md.