Tech:Source Code

From Cyclopath

Cyclopath is open source software under a slightly modified version of the Apache license; see the README for details.

Please note that these directions are incomplete and poorly tested. Also, installation will likely be quite difficult for the first few people as we at Cyclopath HQ have never installed in other environments. In particular, we have not done so without simply copying the Cyclopath database, which we are unable to offer here. However, we felt it was better to release sooner with a difficult install rather than later with a smooth one. Please let us know of any bugs so we can improve things, and please also feel free to edit these wiki pages with what you learn.

The place for discussing the source code, installation, and hacking is the cyclopath-dev mailing list.

[edit] Choosing Tasks

Short answer: Work on what you find interesting and fun!

Here are some tasks that we think are a good way to get started on Cyclopath development: Bugzilla search

And here are some tasks where we especially need help from the open source community: Bugzilla search

[edit] Download source code

Download the following support files:

schema.sql - Database schema
data.sql - Data for a few support tables
elevation.tif - Elevation info (700M)
fixperms - Perl script to help make permissions right. Put it somewhere in your $PATH.

Get the source code with Subversion:

 svn co svn://magic.cyclopath.org/cyclingproject/public/trunk cyclopath

Note: You will want a separate Subversion working directory for each bug/feature/project you're working on, as when you submit a patch (see below) it makes things much easier if it's concise and targeted to only one thing.

[edit] Install it

See:

Tech:Installing -- concise install notes
Tech:Open Source/Install Guide -- comprehensive, includes virtual machine setup and running tips
Slightly different install guide
yes, the docs need unification and work too :)

Note that you do not need to run routed to have a working installation; it's only needed if you want to compute routes.

[edit] Initialize database

This is the part that is likely to be especially rocky for early adopters.

Do a search and replace /export/scratch/reid/postgis-1.3in data.sql with the path where you installed PostGIS.
Run data.sql
Run schema.sql
You now have a valid, but empty database.
Download some map data from MNDOT: http://www.dot.state.mn.us/maps/gisbase/html/datafiles.html (you want one or more of the 7 metro counties)
Use the import scripts in scripts/ to put it in your database.
Run script/nodes_build.py

In theory, you should now have a working Cyclopath database. Let us know how it goes in practice. :)

[edit] Submitting your work to us

[edit] How to write a patch that will get merged quickly

In order to merge your patch quickly, it's helpful if your work follows these guidelines. Basically, your goal is to persuade others that you've (a) solved the right problem and (b) solved it well enough that either your patch can be merged as-is or it's not too hard to convert your patch into one that can be merged.

If you are introducing a new feature or behavior, get consensus that your approach is the right one before starting; otherwise, you might find that people disagree after you've already put a lot of work in!
- If you're working on an existing bug that appears to have reached consensus, you're probably fine.
- Otherwise, propose your behavior on cyclopath-dev and ask for feedback.
Submit concise patches that solve exactly one thing.
Submit patches that follow our coding style.

[edit] Submitting a patch

This is how you send your changes to us for inclusion in the main Cyclopath source tree.

svn update
Resolve any conflicts
svn diff > /tmp/carefully-named-patch.diff
Attach this diff to the relevant bug in Bugzilla
Set the status of that bug to RESOLVED and assign it to @cp-unassigned.

We will then see it and assign it to someone for review.

Note: you'll want to svn update fairly frequently as you work, to reduce the likelihood of difficult conflicts.

[edit] How the review cycle works for volunteers

Volunteer coders work for fun. If some part of your Cyclopath work is not fun, consider doing something else. In particular, if we ask for follow-up work of some kind, you're under no obligation to do it. Just tell us you're not interested, and we'll figure something else out.

Volunteer work is fed into the same review cycle that our developer work with. If we have feedback, changes we like, or ideas for a different approach, we'll share them with you. We might then either take care of them ourselves -- often this is faster, and you still get the benefit of feedback -- or we might ask if you're interested in the follow-up work, in which case you can accept or decline.