CONTRIBUTING.md 8.8 KB
Newer Older
Adrien Pavie's avatar
Adrien Pavie committed
1
2
3
4
5
6
7
# Contributing to iD-indoor

iD-indoor is a fork from original iD editor. If you want to contribute to the simple indoor editor, you can report issues in this repository.

The following concerns the main iD editor, you can follow this for contributing to the core functionnalities of iD.

-------------------------------------------------------------------------------------------------------------------------------------------------
Tom MacWright's avatar
Tom MacWright committed
8
9
10
11

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

12
13
## Code of Conduct

14
15
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.
16

Tom MacWright's avatar
Tom MacWright committed
17
18
19
20
21
## 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:

22
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)
Tom MacWright's avatar
Tom MacWright committed
23
24
25

To report a bug:

26
27
28
29
30
31
* Write specifically what browser (type and version, like "Firefox 43.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.
Tom MacWright's avatar
Tom MacWright committed
32
* Please keep bug reports professional and straightforward: trust us, we share your dismay at software breaking.
33
* If you can, [enable web developer extensions](http://debugbrowser.com/) and report the
34
Javascript error message.
Tom MacWright's avatar
Tom MacWright committed
35
36
37
38
39
40
41
42
43
44

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.

45
46
47
48
49
50
51
52
## Verifying Bug Fixes

To verify a bug fix (or test a new feature), use the [master deployment](http://www.openstreetmap.us/iD/master/)
(http://www.openstreetmap.us/iD/master/), which is updated every 10 minutes with the latest code.

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

Ansis Brammanis's avatar
Ansis Brammanis committed
53
54
## Translating

55
Translations are managed using the
56
[Transifex](https://www.transifex.com/ideditor/id-editor/) platform. After
57
signing up, you can go to [iD's project
58
page](https://www.transifex.com/ideditor/id-editor/), select a language and
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
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
74
Transifex](https://www.transifex.com/ideditor/id-editor/)
75
76
77

To get notifications when translation source files change, click **Watch
project** button near the bottom of the project page. You can edit your
78
[notification settings](https://www.transifex.com/user/settings/notices/) if you're
79
80
81
getting too many notifications.

Translations are licensed under
Bryan Housel's avatar
Bryan Housel committed
82
[ISC](https://raw.github.com/openstreetmap/iD/master/LICENSE), the same license
83
as iD.
Ansis Brammanis's avatar
Ansis Brammanis committed
84

85
86
87
88
89
90
91
92
93
94
95
96
97
98
**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:

![image](https://f.cloud.github.com/assets/98601/324275/1a5cfc8c-9ae0-11e2-9a38-36c0f14d532d.png)

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.

99
100
101
102
103
104
## 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.

105
106
Then, add the new string to `data/core.yaml`. The translation system, Transifex,
will automatically detect the change.
107

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

111
112
113
## Contributing Documentation

Documentation is maintained as a series of [Markdown](http://daringfireball.net/projects/markdown/)
114
115
documents in [core.yaml](/data/core.yaml). The documentation
is in the `help` section (currently starting at line 258). The first line
KathleenLD's avatar
KathleenLD committed
116
of each new section of documentation should be of the form
117
118
119
120
121
122
123

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

KathleenLD's avatar
KathleenLD committed
124
To add a new piece of documentation, simply add to [core.yaml](/data/core.yaml) in the same format as the rest.
125

126
127
## Adding or Refining Presets

128
129
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
130
131
you're going to update the presets, [review the Presets README](/data/presets/README.md).

Tom MacWright's avatar
Tom MacWright committed
132
133
134
135
136
137
138
139
140
141
## 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.

142
Javascript code should pass through [ESLint](http://eslint.org/) with no
Tom MacWright's avatar
Tom MacWright committed
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
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

171
Test your code and make sure it passes.
Tom MacWright's avatar
Tom MacWright committed
172

173
174
175
First ensure you have a `phantomjs` binary, version 2.0 or later, available on your `$PATH`. On a Mac,
you can install this via homebrew with `brew install phantomjs`. Then:

176
177
178
179
1. Go to the directory where you have checked out `iD`
2. run `npm install`
3. run `make`
4. run `npm test` to see whether your tests pass or fail.
Tom MacWright's avatar
Tom MacWright committed
180

John Firebaugh's avatar
John Firebaugh committed
181
182
## Building / Installing

183
184
You can build a concatenated and minified version of iD with the command `make`. Node.js is
required for this.
John Firebaugh's avatar
John Firebaugh committed
185

186
187
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.
John Firebaugh's avatar
John Firebaugh committed
188

Kushan Joshi's avatar
Kushan Joshi committed
189
190
191
192
## Live reloading

You can use [live-server](https://www.npmjs.com/package/live-server) *(npm module)* to
reload the browser automatically whenever there is a change in code.
193

Kushan Joshi's avatar
Kushan Joshi committed
194
1. run `npm install -g live-server`
195
196
2. run  `live-server .` or `live-server dist`
 *(You will be automatically redirected to the local server page.)*
Kushan Joshi's avatar
Kushan Joshi committed
197
198
199

*(Note: Sometimes auto reload might not display correctly and you might need to rebuild iD by running `make`.)*

Tom MacWright's avatar
Tom MacWright committed
200
201
## Licensing

Bryan Housel's avatar
Bryan Housel committed
202
203
204
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.
Tom MacWright's avatar
Tom MacWright committed
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220

## 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`.

221
1. Run `eslint js/id` to make sure your code is clean
Tom MacWright's avatar
Tom MacWright committed
222
223
2. Run tests with `npm test`
3. Commit your changes with an informative commit message
John Firebaugh's avatar
John Firebaugh committed
224
4. [Submit a pull request](https://help.github.com/articles/using-pull-requests) to the `openstreetmap/iD` project.