1Contributing to Leaflet
  2=======================
  3
  4 1. [Getting Involved](#getting-involved)
  5 2. [Reporting Bugs](#reporting-bugs)
  6 3. [Contributing Code](#contributing-code)
  7 4. [Improving Documentation](#improving-documentation)
  8
  9## Getting Involved
 10
 11Third-party patches are absolutely essential on our quest to create the best mapping library that will ever exist.
 12However, they're not the only way to get involved with the development of Leaflet.
 13You can help the project tremendously by discovering and [reporting bugs](#reporting-bugs),
 14[improving documentation](#improving-documentation),
 15helping others on the [Leaflet forum](https://groups.google.com/forum/#!forum/leaflet-js)
 16and [GitHub issues](https://github.com/Leaflet/Leaflet/issues),
 17showing your support for your favorite feature suggestions on [Leaflet UserVoice page](http://leaflet.uservoice.com),
 18tweeting to [@LeafletJS](http://twitter.com/LeafletJS)
 19and spreading the word about Leaflet among your colleagues and friends.
 20
 21## Reporting Bugs
 22
 23Before reporting a bug on the project's [issues page](https://github.com/Leaflet/Leaflet/issues),
 24first make sure that your issue is caused by Leaflet, not your application code
 25(e.g. passing incorrect arguments to methods, etc.).
 26Second, search the already reported issues for similar cases,
 27and if it's already reported, just add any additional details in the comments.
 28
 29After you made sure that you've found a new Leaflet bug,
 30here are some tips for creating a helpful report that will make fixing it much easier and quicker:
 31
 32 * Write a **descriptive, specific title**. Bad: *Problem with polylines*. Good: *Doing X in IE9 causes Z*.
 33 * Include **browser, OS and Leaflet version** info in the description.
 34 * Create a **simple test case** that demonstrates the bug (e.g. using [JSFiddle](http://jsfiddle.net/)).
 35 * Check whether the bug can be reproduced in **other browsers**.
 36 * Check if the bug occurs in the stable version, master, or both.
 37 * *Bonus tip:* if the bug only appears in the master version but the stable version is fine,
 38   use `git bisect` to find the exact commit that introduced the bug.
 39
 40If you just want some help with your project,
 41try asking [on the Leaflet forum](https://groups.google.com/forum/#!forum/leaflet-js) instead.
 42
 43## Contributing Code
 44
 45### Considerations for Accepting Patches
 46
 47While we happily accept patches, we're also commited to keeping Leaflet simple, lightweight and blazingly fast.
 48So bugfixes, performance optimizations and small improvements that don't add a lot of code
 49are much more likely to get accepted quickly.
 50
 51Before sending a pull request with a new feature, first check if it's been discussed before already
 52(either on [GitHub issues](https://github.com/Leaflet/Leaflet/issues)
 53or [Leaflet UserVoice](http://leaflet.uservoice.com/)),
 54and then ask yourself two questions:
 55
 56 1. Are you sure that this new feature is important enough to justify its presense in the Leaflet core?
 57    Or will it look better as a plugin in a separate repository?
 58 2. Is it written in a simple, concise way that doesn't add bulk to the codebase?
 59
 60If your feature or API improvement did get merged into master,
 61please consider submitting another pull request with the corresponding [documentation update](#improving-documentation).
 62
 63### Setting up the Build System
 64
 65To set up the Leaflet build system, install [Node](http://nodejs.org/),
 66then run the following commands in the project root:
 67
 68```
 69npm install -g jake
 70npm install
 71```
 72
 73You can build minified Leaflet by running `jake` (it will be built from source in the `dist` folder).
 74For a custom build with selected components, open `build/build.html` in the browser and follow the instructions from there.
 75
 76### Making Changes to Leaflet Source
 77
 78If you're not yet familiar with the way GitHub works (forking, pull requests, etc.),
 79be sure to check out the awesome [article about forking](https://help.github.com/articles/fork-a-repo)
 80on the GitHub Help website — it will get you started quickly.
 81
 82You should always write each batch of changes (feature, bugfix, etc.) in **its own topic branch**.
 83Please do not commit to the `master` branch, or your unrelated changes will go into the same pull request.
 84
 85You should also follow the code style and whitespace conventions of the original codebase.
 86In particular, use tabs for indentation and spaces for alignment.
 87
 88Before commiting your changes, run `jake lint` to catch any JS errors in the code and fix them.
 89If you add any new files to the Leaflet source, make sure to also add them to `build/deps.js`
 90so that the build system knows about them.
 91
 92Also, please make sure that you have [line endings configured properly](https://help.github.com/articles/dealing-with-line-endings) in Git! Otherwise the diff will show that all lines of a file were changed even if you touched only one.
 93
 94Happy coding!
 95
 96## Running the Tests
 97
 98To run the tests from the command line,
 99install [PhantomJS](http://phantomjs.org/) (and make sure it's in your `PATH`),
100then run:
101
102```
103jake test
104```
105
106To run all the tests in actual browsers at the same time, you can do:
107
108```
109jake test --ff --chrome --safari --ie
110```
111
112To run the tests in a browser manually, open `spec/index.html`.
113
114## Code Coverage
115
116To generate a detailed report about test coverage (which helps tremendously when working on test improvements), run:
117
118```
119jake test --cov
120```
121
122After that, open `spec/coverage/<environment>/index.html` in a browser to see the report.
123From there you can click through folders/files to get details on their individual coverage.
124
125## Improving Documentation
126
127The code of the live Leaflet website that contains all documentation and examples is located in the `gh-pages` branch
128and is automatically generated from a set of HTML and Markdown files by [Jekyll](https://github.com/mojombo/jekyll).
129
130The easiest way to make little improvements such as fixing typos without even leaving the browser
131is by editing one of the files with the online GitHub editor:
132browse the [gh-pages branch](https://github.com/Leaflet/Leaflet/tree/gh-pages),
133choose a certain file for editing (e.g. `reference.html` for API reference),
134click the Edit button, make changes and follow instructions from there.
135Once it gets merged, the changes will immediately appear on the website.
136
137If you need to make edits in a local repository to see how it looks in the process, do the following:
138
139 1. [Install Ruby](http://www.ruby-lang.org/en/) if don't have it yet.
140 2. Run `gem install jekyll`.
141 3. Run `jekyll serve --watch` in the root `Leaflet` folder.
142 4. Open `localhost:4000` in your browser.
143
144Now any file changes will be updated when you reload pages automatically.
145After commiting the changes, just send a pull request.
146
147If you need to update documentation according to a new feature that only appeared in the master version (not stable one),
148you need to make changes to `gh-pages-master` branch instead of `gh-pages`.
149It will get merged into the latter when released as stable.
150
151## Thank You
152
153Not only are we grateful for any contributions, &mdash; helping Leaflet and its community actually makes you AWESOME.
154Join [this approved list of awesome people](https://github.com/Leaflet/Leaflet/graphs/contributors)
155and help us push the limits of what's possible with online maps!