mirror of
https://github.com/FoggedLens/iD.git
synced 2026-02-13 17:23:02 +00:00
365 lines
16 KiB
Markdown
365 lines
16 KiB
Markdown
# 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](CODE_OF_CONDUCT.md) 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](https://github.com/search?l=&q=repo%3Aopenstreetmap%2FiD&type=Issues)
|
|
|
|
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](http://www.cockos.com/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](http://debugbrowser.com/) 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!
|
|
* <sub>[![get-started][get-started]][get-started_link]</sub> -
|
|
Issues are great for new contributors.
|
|
* <sub>[![priority][priority]][priority_link]</sub> -
|
|
Issues that have a big impact or matter most to _new mappers_.
|
|
<br/>(There should probably be 10 or fewer "priority" items.)
|
|
|
|
[get-started]: http://labl.es/svg?text=get-started&bgcolor=0e8a16
|
|
[priority]: http://labl.es/svg?text=priority&bgcolor=0e8a16
|
|
|
|
[get-started_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Aget-started
|
|
[priority_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Apriority
|
|
|
|
Red labels are for **bugs**. These are things that we want fixed, but might be a bit more
|
|
complicted than the green action items.
|
|
|
|
* <sub>[![bug][bug]][bug_link]
|
|
[![bug-release-blocker][bug-release-blocker]][bug-release-blocker_link]
|
|
[![bug-browser-specific][bug-browser-specific]][bug-browser-specific_link]</sub>
|
|
|
|
[bug]: http://labl.es/svg?text=bug&bgcolor=d93f0b
|
|
[bug-release-blocker]: http://labl.es/svg?text=bug-release-blocker&bgcolor=d93f0b
|
|
[bug-browser-specific]: http://labl.es/svg?text=bug-browser-specific&bgcolor=d93f0b
|
|
|
|
[bug_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Abug
|
|
[bug-release-blocker_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Abug-release-blocker
|
|
[bug-browser-specific_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Abug-browser-specific
|
|
|
|
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.
|
|
|
|
* <sub>[![considering][considering]][considering_link]
|
|
[![question][question]][question_link]</sub>
|
|
|
|
[considering]: http://labl.es/svg?text=considering&bgcolor=cc33cc
|
|
[question]: http://labl.es/svg?text=question&bgcolor=cc33cc
|
|
|
|
[considering_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Aconsidering
|
|
[question_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Aquestion
|
|
|
|
Yellow labels are for **chores**. These are the things like code cleanup, upgrades, tests,
|
|
documentation, repository gardening, and other stuff that makes developers happy.
|
|
|
|
* <sub>[![chore][chore]][chore_link]
|
|
[![chore-dependency][chore-dependency]][chore-dependency_link]
|
|
[![chore-documentation][chore-documentation]][chore-documentation_link]
|
|
[![chore-greenkeeper][chore-greenkeeper]][chore-greenkeeper_link]</sub>
|
|
|
|
[chore]: http://labl.es/svg?text=chore&bgcolor=fef2c0
|
|
[chore-dependency]: http://labl.es/svg?text=chore-dependency&bgcolor=fef2c0
|
|
[chore-documentation]: http://labl.es/svg?text=chore-documentation&bgcolor=fef2c0
|
|
[chore-greenkeeper]: http://labl.es/svg?text=chore-greenkeeper&bgcolor=fef2c0
|
|
|
|
[chore_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Achore
|
|
[chore-dependency_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Achore-dependency
|
|
[chore-documentation_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Achore-documentation
|
|
[chore-greenkeeper_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Achore-greenkeeper
|
|
|
|
Light blue labels are for **features**. We use labels to group them into categories.
|
|
|
|
* <sub>[![core][core]][core_link]
|
|
[![localization][localization]][localization_link]
|
|
[![performance][performance]][performance_link]
|
|
[![preset][preset]][preset_link]
|
|
[![renderer][renderer]][renderer_link]
|
|
[![validation][validation]][validation_link]</sub>
|
|
|
|
[core]: http://labl.es/svg?text=core&bgcolor=c5def5
|
|
[localization]: http://labl.es/svg?text=localization&bgcolor=c5def5
|
|
[performance]: http://labl.es/svg?text=performance&bgcolor=c5def5
|
|
[preset]: http://labl.es/svg?text=preset&bgcolor=c5def5
|
|
[renderer]: http://labl.es/svg?text=renderer&bgcolor=c5def5
|
|
[validation]: http://labl.es/svg?text=validation&bgcolor=c5def5
|
|
|
|
[core_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Acore
|
|
[localization_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Alocalization
|
|
[performance_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Aperformance
|
|
[preset_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Apreset
|
|
[renderer_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Arenderer
|
|
[validation_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Avalidation
|
|
|
|
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.
|
|
|
|
* <sub>[![waitfor][waitfor]][waitfor_link]
|
|
[![waitfor-consensus][waitfor-consensus]][waitfor-consensus_link]
|
|
[![waitfor-icon][waitfor-icon]][waitfor-icon_link]
|
|
[![waitfor-info][waitfor-info]][waitfor-info_link]
|
|
[![waitfor-upstream][waitfor-upstream]][waitfor-upstream_link]</sub>
|
|
|
|
[waitfor]: http://labl.es/svg?text=waitfor&bgcolor=444
|
|
[waitfor-consensus]: http://labl.es/svg?text=waitfor-consensus&bgcolor=444
|
|
[waitfor-icon]: http://labl.es/svg?text=waitfor-icon&bgcolor=444
|
|
[waitfor-info]: http://labl.es/svg?text=waitfor-info&bgcolor=444
|
|
[waitfor-upstream]: http://labl.es/svg?text=waitfor-upstream&bgcolor=444
|
|
|
|
[waitfor_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Awaitfor
|
|
[waitfor-consensus_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Awaitfor-consensus
|
|
[waitfor-icon_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Awaitfor-icon
|
|
[waitfor-info_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Awaitfor-info
|
|
[waitfor-upstream_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Awaitfor-upstream
|
|
|
|
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)
|
|
|
|
* <sub>[![wontfix][wontfix]][wontfix_link]
|
|
[![wontfix-confusing][wontfix-confusing]][wontfix-confusing_link]
|
|
[![wontfix-ISATIDL][wontfix-ISATIDL]][wontfix-ISATIDL_link]
|
|
[![wontfix-low-impact][wontfix-low-impact]][wontfix-low-impact_link]</sub>
|
|
|
|
[wontfix]: http://labl.es/svg?text=wontfix&bgcolor=eee
|
|
[wontfix-confusing]: http://labl.es/svg?text=wontfix-confusing&bgcolor=eee
|
|
[wontfix-ISATIDL]: http://labl.es/svg?text=wontfix-ISATIDL&bgcolor=eee
|
|
[wontfix-low-impact]: http://labl.es/svg?text=wontfix-low-impact&bgcolor=eee
|
|
|
|
[wontfix_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aclosed+is%3Aissue+label%3Awontfix
|
|
[wontfix-confusing_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aclosed+is%3Aissue+label%3Awontfix-confusing
|
|
[wontfix-ISATIDL_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aclosed+is%3Aissue+label%3Awontfix-ISATIDL
|
|
[wontfix-low-impact_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aclosed+is%3Aissue+label%3Awontfix-low-impact
|
|
|
|
Special:
|
|
|
|
* <sub>[![bluesky][bluesky]][bluesky_link]</sub> -
|
|
Bluesky issues are extra challenging. They might require weeks of development or not even be possible.
|
|
* <sub>[![wip][wip]][wip_link]</sub> -
|
|
Work in Progress. Don't start work on these, somebody else already did!
|
|
|
|
[bluesky]: http://labl.es/svg?text=bluesky&bgcolor=1d76db
|
|
[wip]: http://labl.es/svg?text=wip&bgcolor=fbca04
|
|
|
|
[bluesky_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Abluesky
|
|
[wip_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Awip
|
|
|
|
## Verifying Bug Fixes
|
|
|
|
To verify a bug fix (or test a new feature), use the [master deployment](http://preview.ideditor.com/master/)
|
|
(http://preview.ideditor.com/master/), which is updated every 10 minutes with the
|
|
latest code and translation 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](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** 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 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.
|
|
|
|
You can check your translations in the [master deployment](http://preview.ideditor.com/master/)
|
|
(http://preview.ideditor.com/master/), which is updated every 10 minutes with the
|
|
latest code and translation strings.
|
|
|
|
[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/user/settings/notices/) if you're
|
|
getting too many notifications.
|
|
|
|
Translations are licensed under
|
|
[ISC](https://raw.github.com/openstreetmap/iD/master/LICENSE), 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](http://wiki.openstreetmap.org/wiki/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 translation 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](http://daringfireball.net/projects/markdown/)
|
|
documents in [core.yaml](/data/core.yaml). The documentation
|
|
is in the `help` section. The first line
|
|
of each new section of documentation should be of the form
|
|
|
|
```markdown
|
|
# 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](/data/core.yaml) in the
|
|
same format as the rest, include your new corresponding `docKey` in
|
|
[/modules/ui/help.js](/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](/data/presets/README.md).
|
|
|
|
|
|
## 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 [ESLint](http://eslint.org/) with no
|
|
warnings. iD uses [ES6 modules](http://exploringjs.com/es6/ch_modules.html) to
|
|
handle connect code together, so we support `import` and `export` constructs.
|
|
|
|
|
|
## 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:
|
|
|
|
```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,
|
|
(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](https://opensource.org/licenses/ISC).
|
|
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](https://help.github.com/articles/using-pull-requests) to the `openstreetmap/iD` project.
|