# 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](https://github.com/systemed/iD/issues/search?q=)

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](http://macwright.org/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](https://www.transifex.com/projects/p/id-editor/) platform. After
signing up, you can go to [iD's project
page](https://www.transifex.com/projects/p/id-editor/), 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](https://www.transifex.com/projects/p/id-editor/)

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](https://www.transifex.com/settings/notices/) if you're
getting too many notifications.

Translations are licensed under
[WTFPL](https://raw.github.com/systemed/iD/master/LICENSE), 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](https://github.com/airbnb/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](http://www.jshint.com/) 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:

```html
<div>
    <div></div>
</div>
```

## CSS

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

```css
.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](http://nodejs.org/)
and a few modules:

1. [Install node.js](http://nodejs.org/) - '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](http://www.wtfpl.net/). 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](https://help.github.com/articles/using-pull-requests) to the `systemed/iD` project.