From 181c4de54780fa988edecab7b270a37685578fe2 Mon Sep 17 00:00:00 2001 From: Quincy Morgan Date: Thu, 18 Jun 2020 09:55:44 -0400 Subject: [PATCH] Update CONTRIBUTING.md --- CONTRIBUTING.md | 98 +++++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 47 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9acf6a467..5dd9d1474 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,23 +1,20 @@ # 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. +Thinking of contributing to iD? High five! There are plenty of ways to get involved. +You don't need to know the first thing about programming (though it's always a +great time to learn!) + +Everyone involved in the iD project is subject to the [Code of Conduct](CODE_OF_CONDUCT.md). +Please take a moment to read it before proceeding, it's short and simple. We want +everyone to feel comfortable contributing to iD. -## Code of Conduct +## Submitting Issues -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. +We'd love to hear your feedback about iD. Please [search existing issues](https://github.com/search?l=&q=repo%3Aopenstreetmap%2FiD&type=Issues) +before [opening a new one](https://github.com/openstreetmap/iD/issues/new). Many bugs and ideas have already been posted. - -## 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: +When reporting a bug: * Write specifically what browser (type and version, like "Firefox 49.0"), OS, and browser extensions you have installed @@ -29,18 +26,17 @@ You can drag the image file onto the GitHub issue and it will be included with y * 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, over-describe the bug and how you discovered it. -When in doubt, be over-descriptive of the bug and how you discovered it. +When requesting a feature: -To request a feature: - -* If the feature is available in some other software (like Potlatch), link to that software and the implementation. +* Provide a link if the feature is available in some other software. 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. +* Understand that iD is focused on simplicity and doesn't aim to be + as complete as JOSM or other editors. -## Issue Labels +### Issue Labels We use GitHub labels to keep track of issues. Some guidelines: @@ -183,14 +179,21 @@ Work in Progress. Don't start work on these, somebody else already did! [wip_link]: https://github.com/openstreetmap/iD/issues?q=is%3Aopen+is%3Aissue+label%3Awip -## Verifying Bug Fixes +## Testing -To verify a bug fix (or test a new feature), use the [develop deployment](http://preview.ideditor.com/master/) -(http://preview.ideditor.com/master/), which is updated every 10 minutes with the -latest code and translation strings. +You can use the [development preview site](https://ideditor.netlify.app) to test +unreleased features and verify bug fixes, all without building iD yourself. This site +is updated with the latest code and translations every time we change the `develop` branch. -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. +The deployments on https://openstreetmap.org and https://preview.ideditor.com/release +are updated only with [stable releases](https://github.com/openstreetmap/iD/releases). +Recently fixed issues may still be present on these sites until the next version of iD +is released. + +While it's possible to edit the live OpenStreetMap database with development versions +of iD, it's risky to do so. Your edits could be lost or garbled at any time. Press +the ![live](http://labl.es/svg?text=live&bgcolor=d32232) button in the bottom bar to +switch to the development database. ## Translating @@ -216,9 +219,8 @@ 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. +You can check your translations on the [development preview site](https://ideditor.netlify.app), +which is updated every time we change the `develop` branch. [iD translation project on Transifex](https://www.transifex.com/projects/p/id-editor/) @@ -253,11 +255,11 @@ These are separate translations for uniformity reasons and because some language Note that if you want to add/update English translations in Osmose then you will need to head on over to the [Osmose backend source code](https://github.com/osm-fr/osmose-backend). -## Adding New Strings for Translation or Updating Existing Strings +### Translations in Code -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. +iD translates strings with a `t` function: `t('foo.bar')` translates the key +`foo.bar` into the current language. If you introduce new translatable strings, +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. @@ -295,7 +297,13 @@ 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 +## Contributing Code + +We like when people get involved! iD is a busy project, so it helps if you first +open an issue to ask whether an idea makes sense, +instead of surprising us with a pull request. + +### JavaScript Legacy iD code was written with ES5 syntax, however we now support most ES6 syntax via [Rollup.js](https://rollupjs.org/guide/en) and the [Rollup Bublé plugin](https://github.com/rollup/plugins/tree/master/packages/buble). You can find details about Bublé [here](https://buble.surge.sh/guide/). @@ -312,7 +320,7 @@ Always spaces, never tabs. JavaScript code should pass through [ESLint](http://eslint.org/) with no warnings. -## HTML +### 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: @@ -324,7 +332,7 @@ always, indented by the level of the tree: ``` -## CSS +### CSS Just like HTML and JavaScript, 4 space soft tabs always. @@ -338,7 +346,7 @@ We write vanilla CSS with no preprocessing step. Since iD targets modern browser (Chrome, Firefox, Safari, Opera, IE11, and Edge) feel free to use newer features wisely. -## Tests +### Tests Test your code and make sure it passes. @@ -347,7 +355,7 @@ Test your code and make sure it passes. 3. run `npm test` to see whether your tests pass or fail. -## Building / Installing +### Building / Installing You can rebuild iD completely with the command `npm run all`. @@ -355,7 +363,7 @@ iD will be built to the `dist` directory. This directory is self-contained; you into the public directory of your webserver to deploy iD. -## Licensing +### 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 @@ -364,10 +372,6 @@ 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 @@ -398,7 +402,7 @@ Additionally here is a step-by-step workflow example for beginners: 4. Clone or download your local copy of iD from your GitHub account using https `git clone https://github.com//iD.git` or using ssh `git clone git@github.com:{{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 `. Never do anything in develop branch. +5. Switch to the iD directory, create a working branch (choose a descriptive name) and switch to it : `cd iD ; git checkout -b `. Never do anything in the `develop` branch. 6. Edit file(s) and try your change locally (See above). @@ -419,11 +423,11 @@ you can clean up by deleting the branch from your GitHub-iD-Clone and your local ### 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 develop with whatever is in our develop. If you have not done so yet: Add the main repo as an "upstream" remote: +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 `develop` with whatever is in our `develop`. If you have not done so yet: Add the main repo as an "upstream" remote: `git remote add upstream git@github.com:openstreetmap/iD.git` -Then change to the develop branch and get everything from upstream (the main repository) +Then change to the `develop branch and get everything from upstream (the main repository) `git checkout develop ; git fetch --all && git reset --hard upstream/develop`