Skip to content

Latest commit

 

History

History
126 lines (83 loc) · 4.38 KB

CONTRIBUTING.md

File metadata and controls

126 lines (83 loc) · 4.38 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.

Verifying Bug Fixes

To verify a bug fix (or test a new feature), use the test instance.

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. Documentation is shown in alphabetical order, so most documentation is prefixed with 02- and so on in order to keep it in a certain order.

To add a new piece of documentation, simply add to core.yaml in the same format as the rest.

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.

master-dump2

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 ESLint 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 version 0.10.0 or later - '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 a concatenated and minified version of iD with the command make. Node.js is required for this.

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 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 eslint 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 openstreetmap/iD project.