CONTRIBUTING.md

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.

Code of Conduct

We want everyone to feel comfortable contributing to iD. Please read the project Code of Conduct and remember to be nice to one another.

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 49.0"), 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?
• We love screenshots. If you can take a picture of the issue, that is extra helpful. You can drag the image file onto the GitHub issue and it will be included with your bug report.
• You can use a program like LICEcap to record an animated gif.
• 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.

Issue Labels

We use GitHub labels to keep track of issues. Some guidelines:

Green labels are for action items. Jump in and start working!

• - Best for new contributors. No experience necessary!
• - For more intermediate contributors, probably requires investigation or knowledge of iD code.
• - Issues that have a big impact or matter most to new mappers.
  (There should probably be 10 or fewer "priority" items.)

Red labels are for bugs. These are things that we want fixed, but might be a bit more complicated than the green action items.

• 

Purple labels are for non-action items. These might be a question or feature request that needs some discussion about whether it belongs in iD. Discuss before working on these.

• 

Yellow labels are for chores. These are the things like code cleanup, upgrades, tests, documentation, repository gardening, and other stuff that makes developers happy.

• 

Light blue labels are for features. We use labels to group them into categories.

• 

Dark Grey labels are for waitfor items. We won't work on these now, but we'll keep the issues open while we wait for something to happen.

• 

Light Grey labels are for wontfix items. We've decided these doesn't belong in iD at this time. Don't feel bad, sometimes we change our minds later and revisit them! (ISATIDL = "I saw a thing I don't like", a common OpenStreetMap complaint)

• 

Special:

• - Bluesky issues are extra challenging. They might require weeks of development or not even be possible.
• - Work in Progress. Don't start work on these, somebody else already did!

Verifying Bug Fixes

To verify a bug fix (or test a new feature), use the master deployment (http://preview.ideditor.com/master/), which is updated every 10 minutes with the latest code and translations strings.

The deployments on openstreetmap.org and http://preview.ideditor.com/release/ are updated only with stable releases. Issues that are marked fixed in the tracker may still be present.

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 to start translating. Translations are divided into separate resources:

• core - contains text for the main interface of iD
• presets - contains the text for labeling feature presets
• imagery - contains text for imagery names and descriptions

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 translations 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.

You can check your translations in the master deployment (http://preview.ideditor.com/master/), which is updated every 10 minutes with the latest code and translations strings.

iD translation project on Transifex

To get notifications when translations 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 ISC, the same license as iD.

Why are there so many duplicate "Type" translations? There are multiple distinct preset fields with the label "Type". You can see some context on the "Details" tab in Transifex:

The "key" field indicates that this is the "Type" label for the "aeroway" preset, i.e. you should translate it as you would translate "type" in "type of aeroway".

These are separate translations for uniformity reasons and because some languages may translate "type" differently in "type of aeroway" and "type of amenity", for example.

Adding New Strings for Translation or Updating Existing Strings

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. The translations system, Transifex, will automatically detect the change.

If you are updating an existing string, update it in data/core/yaml and run npm run build to generate the en.json file automatically, then commit both modified files.

Use npm run build to build the translations with the local changes.

npm run translations can be used to pull the latest translations from Transifex.

Contributing Documentation

Documentation is maintained as a series of Markdown documents in core.yaml. The documentation is in the help section. The first line of each new section of documentation should be of the form

# GPS

This will be used for navigation and as its title in iD. To add a new piece of documentation, simply add to /data/core.yaml in the same format as the rest, include your new corresponding docKey in /modules/ui/help.js and call npm run build.

Adding or Refining Presets

Presets save time for iD users by automatically showing them the tags they are likely to add for a given feature. They are stored in data/presets/presets. If you're going to update the presets, review the Presets README.

JavaScript

iD uses ES5 syntax throughout the code, with one exception: ES6 modules using import and export constructs. These are processed by Rollup.js and not present in the distributed iD bundle.

ES5 syntax is required for:

• IE11, which about 15-20% of our users still use
• PhantomJS which runs our tests (it would be great to replace this!)

We will introduce ES6 syntax eventually when it makes sense to do so.

We use the ES5 Airbnb style guide 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 datasets, ever.

JavaScript code should pass through ESLint with no warnings.

HTML

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

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

CSS

Just like HTML and JavaScript, 4 space soft datasets always.

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

We write vanilla CSS with no preprocessing step. Since iD targets modern browsers, (Chrome, Firefox, Safari, Opera, IE11, and Edge) feel free to use newer features wisely.

Tests

Test your code and make sure it passes.

1. Go to the directory where you have checked out iD
2. run npm install
3. run npm test to see whether your tests pass or fail.

Building / Installing

You can rebuild iD completely with the command npm run all.

iD will be built to the dist directory. This directory is self-contained; you can copy it into the public directory of your webserver to deploy iD.

Licensing

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

Submitting Changes

We like when people get involved! iD is a busy project, and it helps the maintainers if you first open an issue to ask whether an idea makes sense, instead of surprising us with a pull request.

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

git checkout -b fix-the-thing

Make your changes to source files under modules/. The iD.js and iD.min.js files in this project are autogenerated - don't edit them.

1. Try your change locally. Run npm start and visit localhost:8080 in a browser.
2. Run lint and tests with npm test
3. Commit your changes with an informative commit message
4. Submit a pull request to the openstreetmap/iD project.

Using GitHub and git

If you are new to GitHub or git you can read the GitHub Guides "Understanding the GitHub Flow", "Git Handbook" and "Forking Projects" could be especially interesting to you.

Step by Step

Additionally here is a step-by-step workflow example for beginners:

1. Login to your GitHub account or create a GitHub account, if you do not already have one.

2. Go to the iD main repository and fork iD into your GitHub account (Fork is top right).

3. Set up Git and prepare for Authenticating with GitHub from Git.

4. Clone or download your local copy of iD from your GitHub account using https git clone https://github.com/<yourgithubaccount>/iD.git or using ssh git clone [email protected]:{{yourgithubaccount}}/iD.git. In your local copy you'll have a "remote" called origin.

5. Switch to the iD directory, create a working branch (choose a descriptive name) and switch to it : cd iD ; git checkout -b <working-branch-name>. Never do anything in master branch.

6. Edit file(s) and try your change locally (See above).

7. Add Files and commit them git add <files> ; git commit -m "Description of what you did" .. repeat as needed ..

8. Push Changes to your GitHub account git push origin <working-branch-name>. The next push also works without the branch name: git push origin.

9. Go to GitHub for your fork of iD at https://github.com/{{yourgithubaccount}}/iD. GitHub will already know about your recently pushed branch, and ask if you want to create a Pull Request for it.

10. Your Pull Request will be seen by the maintainers of iD. They can merge it or ask for changes. You can update your Pull Request with Steps 7 and 8, Step 9 is required only once per Pull Request.

Clean Up

After your Pull Request gets merged into the main repository you can clean up by deleting the branch from your GitHub-iD-Clone and your local directory

git push --delete origin <working-branch-name> ; git branch -d <working-branch-name>

Restart with another PR after some while

If you did not use your copy of iD for some while, other Pull Request gets merged and you don't have the latest version of iD. You can replace your master with whatever is in our master. If you have not done so yet: Add the main repo as an "upstream" remote:

git remote add upstream [email protected]:openstreetmap/iD.git

Then change to the master branch and get everything from upstream (the main repository)

git checkout master ; git fetch --all && git reset --hard upstream/master

Submitting directly in the Browser

If you want to submit Documentation, Spelling improvements, etc. which do not need testing, you can do this with your browser in GitHub. Please don't use this to change Code and create untested Pull Requests. You also need a GitHub account and may find this Article about Editing and this Article about Pull Requests usefull.

Step by Step with Browser

Additionally here is a step-by-step workflow example for beginners:

1. Login to your GitHub account or create a GitHub account, if you do not already have one.

2. Go to the iD main repository and fork iD into your GitHub account (Fork is top right).

3. Create a New Branch by clicking on "Branch: master" and entering the name of a new branch (choose a descriptive name).

4. Navigate to the file you want to edit and click on "Edit this file" and apply your changes to the file. Alternatively, you could also "Create a new file".

5. When finished editing the file enter a commit text (the description is optional) and commit directly to the newly created branch. You may repeat 4 and 5 until all required changes are commited.

6. Navigate back to your "id" project - https://github.com/{{yourgithubaccount}}/iD

7. Follow this Article about Pull Requests to create a new pull request for your change