Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

155 lines (107 sloc) 5.833 kb

Contributing to iD

Thinking of contributing to iD? High five! Here are some basics for our habits so that you can write code that fits in perfectly.

Reporting Issues

We'd love to hear what you think about iD, about any specific problems or concerns you have. Here's a quick list of things to consider:

Please search for your issue before filing it: many bugs and improvements have already been reported

To report a bug:

  • Write specifically what browser (type and version, like Firefox 22), OS, and browser extensions you have installed
  • Write steps to replicate the error: when did it happen? What did you expect to happen? What happened instead?
  • Please keep bug reports professional and straightforward: trust us, we share your dismay at software breaking.
  • If you can, enable web developer extensions and report the Javascript error message.

When in doubt, be over-descriptive of the bug and how you discovered it.

To request a feature:

  • If the feature is available in some other software (like Potlatch), link to that software and the implementation. We care about prior art.
  • Understand that iD is meant to be a simple editor and doesn't aim to be as complete or complicated as JOSM or similar.

Translating

Translations are managed using the Transifex platform. After signing up, you can go to iD's project page, select a language and click Translate now to start translating. Translations are divided into two sections, core, which contains text for the main interface of iD, and presets, which has the text for labeling feature presets.

The words in brackets, for example {name}, should not be translated into a new language: it's replaced with a place name when iD presents the text. So a French translation of Couldn't locate a place named '{name}' would look like Impossible de localiser l'endroit nommé '{name}'.

The translations for presets consist of the names of presets, labels for preset fields, and lists of search terms. You do not need to translate the search terms literally -- use a set of synonyms and related terms appropriate to the target language, separated by commas.

iD translation project on Transifex

To get notifications when translation source files change, click Watch project button near the bottom of the project page. You can edit your notification settings if you're getting too many notifications.

Translations are licensed under WTFPL, the same license as iD.

Adding New Strings for Translation

iD translates strings with a t function - t('foo.bar') translate the key foo.bar into the current language. If you introduce new translatable strings to iD, only display them in the interface through the t() function.

Then, add the new string to data/core.yaml or data/presets.yaml (depending on whether it pertains to core code or presets). The translation system, Transiflex, will automatically detect the change.

Use make to build the translations with the local changes. make translate can be used to pull the latest translations from Transifex.

Javascript

We use the Airbnb style for Javascript with only one difference:

4 space soft tabs always for Javascript, not 2.

No aligned =, no aligned arguments, spaces are either indents or the 1 space between expressions. No hard tabs, ever.

Javascript code should pass through JSHint with no warnings.

HTML

There isn't much HTML in iD, but what there is is similar to JS: 4 spaces always, indented by the level of the tree:

<div>
    <div></div>
</div>

CSS

Just like HTML and Javascript, 4 space soft tabs always.

.radial-menu-tooltip {
    background: rgba(255, 255, 255, 0.8);
}

We write vanilla CSS with no preprocessing step. Since iD targets modern browsers, feel free to use newer features wisely.

Tests

Test your code and make sure it passes. Our testing harness requires node.js and a few modules:

  1. Install node.js - 'Install' will download a package for your OS
  2. Go to the directory where you have checked out iD
  3. Run npm install
  4. Run npm test to see whether your tests pass or fail.

Building / Installing

You can build and install a concatenated and minified version of iD with the command make install. Node.js is required for this.

By default iD will be built to the build directory, but you can move it elsewhere or specify the build location with make install install_root=/path/to/install.

Licensing

iD is under the WTFPL. Some of the libraries it uses are under different licenses. If you're contributing to iD, you're contributing WTFPL code.

Submitting Changes

Let's say that you've thought of a great improvement to iD - a change that turns everything red (please do not do this, we like colors other than red).

In your local copy, make a branch for this change:

git checkout -b make-red

Make your changes to source files. By source files we mean the files in js/. the iD.js and iD.min.js files in this project are autogenerated - don't edit them.

So let's say you've changed js/ui/confirm.js.

  1. Run jshint js/id to make sure your code is clean
  2. Run tests with npm test
  3. Commit your changes with an informative commit message
  4. Submit a pull request to the systemed/iD project.
Jump to Line
Something went wrong with that request. Please try again.