Skip to content

DevelopersGuide

Jump to bottom Edit New page
Andrew Byrd edited this page Jul 18, 2013 · 35 revisions

Developers Guide

This page contains developer-centric information about the OpenTripPlanner project.

Getting the code and installation

See the installation instructions for details on how to check out the code and get set up with a development environment.

You can also just clone the git repository:

$ git clone git://github.com/openplans/OpenTripPlanner.git

Contributing to the project

OpenTripPlanner is a community based open source project, and we welcome all who wish to contribute. There are several ways to get involved:

  • Join the developer mailing list

  • Fix typos and improve the documentation on the wiki.

  • File a bug or new feature request.

  • Submit patches. If you're not yet a committer, please attach patches to the relevant issue. A pull request for the relevant issue is probably the easiest way to do this.

  • Become a committer. If you'd like to contribute code to the project beyond the occasional patch, you can request commit rights for the project. Before doing so, you should:

  1. Make yourself known to the rest of the community by introducing yourself on the mailing list, hanging out in the IRC channel, and/or joining one of our weekly phone or irc meetings.

  2. Submit at least two patchs to the mailing list (or via a github pull request) for review. It doesn't have to be perfect, and it doesn't have be huge, but it should do something useful (e.g., fix a bug, add a new feature, make the code faster/more efficient, etc).

Project proposals and decision making

Decisions are made by the OpenTripPlanner community through a proposal and informal voting process on the project mailing list. Learn more.

Project modules

The OpenTripPlanner project is composed of a number of different modules. These are:

  • opentripplanner-routing. The core routing engine. This includes the vertex and edge classes and interfaces that compose the graph structure and the algorithms used for finding the shortest path in the graph.

  • opentripplanner-graph-builder. This is a command-line utility used for turning raw transit and street data into a compiled graph that can be routed on. See the GraphBuilder page for more details.

  • opentripplanner-api-webapp A web application that exposes a RESTful API for making requests to the trip planner. This module requires the opentripplanner-routing module as well as a graph object compiled by the opentripplanner-graph-builder module.

  • opentripplanner-webapp. A front-end web application and user interface that communicates with the opentripplanner-api-webapp. The code is based on TriMet's existing trip planner UI. Future plans call for a (set of) MobileDevice ui(s).

  • opentripplanner-gui. A graphical interface for visualizing graph data compiled by the opentripplanner-graph-builder module. This is mostly helpful for troubleshooting and debugging purposes, as it allows you to quickly explore a graph.

  • opentripplanner-integration. A set of integration sets useful used both for testing that the entire system works together and for getting started with the project quickly. The tests will automatically generate a compiled graph using GTFS and OSM data for Portland and run the API and trip planner web app so you can try out planning trips.

  • opentripplanner-api-extended Exposes a RESTful API used by the optional system map view in the webapp. Note: This module is experimental, and both its implementation and the interface it exposes are subject to change substantially.

  • opentripplanner-utils Some minor utility functions.

Developer Docs

If you're not super familiar with transit, GIS, etc, you may want to learn some of the JargonAndAcronyms.

Tickets and checkins

All checkins should reference a specific ticket (decided in #175). For example, Fixes #9999 (spaceships aren't supported by routing engine). If no ticket exists for the feature or bug your code implements or fixes, you should create a new ticket prior to checking in.

Github will automatically update tickets on checkin. If your commit message includes the text fixes #123, it will automatically append your message as a comment on the ticket and close it. If you simply mention #123 in your message, your message will be appended to the ticket but it will remain open.

Synonyms for closing tickets (append comment and close):

fixes #xxx
fixed #xxx
fix #xxx
closes #xxx
close #xxx
closed #xxx

Comments & code documentation

As a matter of policy, all new methods, classes, and fields should include comments explaining what they are for and any other pertinent information. For Java code, the comments should use the JavaDoc conventions. When documenting fields with getters and setters, the comments should go with the getter.

Date format

Please use only ISO 8601 date format (YYYY-MM-DD) on the wiki and throughout the project. This avoids the ambiguity that can result from differing local interpretations of date formats like 02/01/12.

Code style

Java

OpenTripPlanner uses the same code formatting and style as the GeoTools and GeoServer projects. It's a minor variant of the Sun coding convention. Notably, we do not use tabs and we allow for lines up to 100 characters wide.

The Eclipse formatter config supplied by the GeoTools project allows comments up to 150 characters wide. A modified version included in the OpenTripPlanner repository will wrap comments to the same width as lines of code, which makes for easier reading in a narrow window.

If you use Eclipse, you should do the following to make sure your code is automatically formatted correctly:

  1. Open the project Properties (right-click on the project directory in Eclipse and select Properties or choose Project -> Properties).

  2. Select Java, then Code Style, and finally Formatter.

  3. Check the Enable project specific settings checkbox.

  4. Click Import..., select the formatter.xml file in the root of the OpenTripPlanner git repository, and click Open.

  5. Click OK to close the Properties window.

JavaScript

As of #206, we follow Crockford's JavaScript code conventions. Further guidelines include:

  • All .js source files should contain one class only

  • Capitalize the class name, as well as the source file name (a la Java)

  • Include the GNU LGPL header at top of file, i.e., /* This program is free software:...*/

  • Include the namespace definition in each and every file: otp.namespace("otp.configure");

  • Include a class comment. For example,

    /**
     * Configure Class
     *
     * Purpose is to allow a generic configuration object to be read via AJAX/JSON, and inserted into an Ext Store
     * The implementation is TriMet route map specific...but replacing ConfigureStore object (or member variables) with
     * another implementation, will give this widget flexibility for other uses beyond the iMap.
     *
     * @class
     */

Note: There is still a lot of code following other style conventions. We are reformatting as we write new code and refactor.

Add a custom footer
Add a custom sidebar
Clone this wiki locally