2012-10-09 22:34:20 +08:00
Contributing to Leaflet
=======================
2012-10-10 23:07:07 +08:00
1. [Getting Involved ](#getting-involved )
2. [Reporting Bugs ](#reporting-bugs )
3. [Contributing Code ](#contributing-code )
4. [Improving Documentation ](#improving-documentation )
2016-01-13 18:53:28 +08:00
5. [Code of Conduct ](#code-of-conduct )
2012-10-09 22:34:20 +08:00
## Getting Involved
2012-11-15 19:58:09 +08:00
Third-party patches are absolutely essential on our quest to create the best mapping library that will ever exist.
2014-12-18 10:03:58 +08:00
However, they're not the only way to get involved with Leaflet development.
You can help the project tremendously by discovering and [reporting bugs ](#reporting-bugs );
[improving documentation ](#improving-documentation );
2015-11-27 22:22:05 +08:00
helping others on [Stack Overflow ](https://stackoverflow.com/questions/tagged/leaflet ),
[GIS Stack Exchange ](https://gis.stackexchange.com/questions/tagged/leaflet )
2014-12-18 10:03:58 +08:00
and [GitHub issues ](https://github.com/Leaflet/Leaflet/issues );
showing your support for your favorite feature suggestions on [Leaflet UserVoice page ](http://leaflet.uservoice.com );
tweeting to [@LeafletJS ](http://twitter.com/LeafletJS );
2012-11-15 19:58:09 +08:00
and spreading the word about Leaflet among your colleagues and friends.
2012-10-09 22:34:20 +08:00
## Reporting Bugs
2013-01-11 19:42:15 +08:00
Before reporting a bug on the project's [issues page ](https://github.com/Leaflet/Leaflet/issues ),
2012-11-15 19:58:09 +08:00
first make sure that your issue is caused by Leaflet, not your application code
(e.g. passing incorrect arguments to methods, etc.).
Second, search the already reported issues for similar cases,
and if it's already reported, just add any additional details in the comments.
2012-10-10 16:54:22 +08:00
2014-12-18 10:03:58 +08:00
After you've made sure that you've found a new Leaflet bug,
2012-11-15 19:58:09 +08:00
here are some tips for creating a helpful report that will make fixing it much easier and quicker:
2012-10-10 16:54:22 +08:00
2012-10-10 17:33:08 +08:00
* Write a **descriptive, specific title** . Bad: *Problem with polylines* . Good: *Doing X in IE9 causes Z* .
2012-10-10 16:54:22 +08:00
* Include **browser, OS and Leaflet version** info in the description.
2016-04-20 19:31:13 +08:00
* Create a **simple test case** that demonstrates the bug (e.g. using [Leaflet playground ](http://playground-leaflet.rhcloud.com/ )).
2012-10-10 17:33:08 +08:00
* Check whether the bug can be reproduced in **other browsers** .
2012-10-10 16:54:22 +08:00
* Check if the bug occurs in the stable version, master, or both.
2012-11-15 19:58:09 +08:00
* *Bonus tip:* if the bug only appears in the master version but the stable version is fine,
use `git bisect` to find the exact commit that introduced the bug.
2012-10-09 22:34:20 +08:00
2013-04-20 18:27:16 +08:00
If you just want some help with your project,
2015-11-27 22:22:05 +08:00
try asking on [Stack Overflow ](https://stackoverflow.com/questions/tagged/leaflet )
or [GIS Stack Exchange ](https://gis.stackexchange.com/questions/tagged/leaflet ) instead.
2013-04-20 18:27:16 +08:00
2012-10-09 22:34:20 +08:00
## Contributing Code
2012-10-10 23:07:07 +08:00
### Considerations for Accepting Patches
2014-07-01 07:46:20 +08:00
While we happily accept patches, we're also committed to keeping Leaflet simple, lightweight and blazingly fast.
2012-11-15 19:58:09 +08:00
So bugfixes, performance optimizations and small improvements that don't add a lot of code
are much more likely to get accepted quickly.
2012-10-10 17:33:08 +08:00
2014-12-18 10:03:58 +08:00
Before sending a pull request with a new feature, check if it's been discussed before already
2013-01-11 19:42:15 +08:00
(either on [GitHub issues ](https://github.com/Leaflet/Leaflet/issues )
2012-11-15 19:58:09 +08:00
or [Leaflet UserVoice ](http://leaflet.uservoice.com/ )),
2014-12-18 10:03:58 +08:00
and ask yourself two questions:
2012-10-10 17:33:08 +08:00
2014-07-01 07:46:20 +08:00
1. Are you sure that this new feature is important enough to justify its presence in the Leaflet core?
2012-11-15 19:58:09 +08:00
Or will it look better as a plugin in a separate repository?
2012-10-10 23:07:07 +08:00
2. Is it written in a simple, concise way that doesn't add bulk to the codebase?
2012-11-15 19:58:09 +08:00
If your feature or API improvement did get merged into master,
please consider submitting another pull request with the corresponding [documentation update ](#improving-documentation ).
2012-10-10 23:07:07 +08:00
2012-10-31 22:49:14 +08:00
### Setting up the Build System
2014-12-28 09:39:18 +08:00
The Leaflet build system uses [Node ](http://nodejs.org/ ), and the [Jake ](http://jakejs.com/ ) Javascript build tool.
To set up the Leaflet build system, install Node then run the following commands in the project root to install Jake:
2012-10-31 22:49:14 +08:00
```
npm install -g jake
2013-04-20 18:27:16 +08:00
npm install
2012-10-31 22:49:14 +08:00
```
You can build minified Leaflet by running `jake` (it will be built from source in the `dist` folder).
2013-04-20 18:27:16 +08:00
For a custom build with selected components, open `build/build.html` in the browser and follow the instructions from there.
2012-10-31 22:49:14 +08:00
2012-10-10 23:07:07 +08:00
### Making Changes to Leaflet Source
2012-11-15 19:58:09 +08:00
If you're not yet familiar with the way GitHub works (forking, pull requests, etc.),
be sure to check out the awesome [article about forking ](https://help.github.com/articles/fork-a-repo )
on the GitHub Help website — it will get you started quickly.
2012-10-10 23:07:07 +08:00
2012-11-15 19:58:09 +08:00
You should always write each batch of changes (feature, bugfix, etc.) in **its own topic branch** .
Please do not commit to the `master` branch, or your unrelated changes will go into the same pull request.
2012-10-10 23:07:07 +08:00
2013-04-20 18:27:16 +08:00
You should also follow the code style and whitespace conventions of the original codebase.
2013-01-31 19:25:18 +08:00
In particular, use tabs for indentation and spaces for alignment.
2012-10-10 23:07:07 +08:00
2014-07-01 07:46:20 +08:00
Before committing your changes, run `jake lint` to catch any JS errors in the code and fix them.
2012-11-15 19:58:09 +08:00
If you add any new files to the Leaflet source, make sure to also add them to `build/deps.js`
so that the build system knows about them.
2012-10-31 22:49:14 +08:00
2013-02-16 04:01:11 +08:00
Also, 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.
2012-10-31 22:49:14 +08:00
Happy coding!
2012-10-09 22:34:20 +08:00
2013-04-20 18:27:16 +08:00
## Running the Tests
2013-02-19 09:54:13 +08:00
2013-04-20 18:27:16 +08:00
To run the tests from the command line,
install [PhantomJS ](http://phantomjs.org/ ) (and make sure it's in your `PATH` ),
then run:
2013-02-19 09:54:13 +08:00
2013-04-20 18:27:16 +08:00
```
jake test
```
2013-02-19 09:54:13 +08:00
2013-04-20 18:27:16 +08:00
To run all the tests in actual browsers at the same time, you can do:
2013-02-19 09:54:13 +08:00
2013-04-20 18:27:16 +08:00
```
2013-04-20 18:44:31 +08:00
jake test --ff --chrome --safari --ie
2013-04-20 18:27:16 +08:00
```
2013-02-19 09:54:13 +08:00
2013-04-20 18:27:16 +08:00
To run the tests in a browser manually, open `spec/index.html` .
2013-02-19 09:54:13 +08:00
## Code Coverage
2013-04-20 18:27:16 +08:00
To generate a detailed report about test coverage (which helps tremendously when working on test improvements), run:
2013-02-19 09:54:13 +08:00
2013-04-20 18:27:16 +08:00
```
jake test --cov
```
2013-02-19 09:54:13 +08:00
2013-04-20 18:27:16 +08:00
After that, open `spec/coverage/<environment>/index.html` in a browser to see the report.
From there you can click through folders/files to get details on their individual coverage.
2013-02-19 09:54:13 +08:00
2012-10-09 22:34:20 +08:00
## Improving Documentation
2012-11-15 19:58:09 +08:00
The code of the live Leaflet website that contains all documentation and examples is located in the `gh-pages` branch
2015-02-14 20:12:44 +08:00
and is automatically generated from a set of HTML and Markdown files by [Jekyll ](http://jekyllrb.com/ ).
2012-10-10 23:07:07 +08:00
2012-11-15 19:58:09 +08:00
The easiest way to make little improvements such as fixing typos without even leaving the browser
is by editing one of the files with the online GitHub editor:
2013-01-11 19:42:15 +08:00
browse the [gh-pages branch ](https://github.com/Leaflet/Leaflet/tree/gh-pages ),
2016-04-20 19:31:13 +08:00
choose a certain file for editing (e.g. `plugins.html` for the list of Leaflet plugins),
2012-11-15 19:58:09 +08:00
click the Edit button, make changes and follow instructions from there.
Once it gets merged, the changes will immediately appear on the website.
2012-10-10 23:07:07 +08:00
If you need to make edits in a local repository to see how it looks in the process, do the following:
1. [Install Ruby ](http://www.ruby-lang.org/en/ ) if don't have it yet.
2. Run `gem install jekyll` .
2013-06-26 04:25:21 +08:00
3. Run `jekyll serve --watch` in the root `Leaflet` folder.
4. Open `localhost:4000` in your browser.
2012-10-10 23:07:07 +08:00
2013-06-26 04:25:21 +08:00
Now any file changes will be updated when you reload pages automatically.
2014-07-01 07:46:20 +08:00
After committing the changes, just send a pull request.
2012-10-10 23:07:07 +08:00
2016-04-20 19:31:13 +08:00
### API documentation
Since Leaflet 1.0.0-rc1, the API documentation in `reference-1.0.0.html` is handled
via [Leafdoc ](https://github.com/Leaflet/Leafdoc ). This means that next to the
code for every method, option or property there is a special code comment documenting
that feature. In order to edit the API documentation, just edit these comments in the
source code.
In order to generate the documentation, just run
```
jake docs
```
and you'll find a `.html` file in the `dist/` directory.
On every release of a new Leaflet version, this file will be generated and copied
over to the `gh-pages` branch - there is no need to send pull requests to this
branch anymore to update the API documentation.
2012-10-10 23:07:07 +08:00
2016-01-13 18:53:28 +08:00
## Code of Conduct
Everyone is invited to participate in the Leaflet community and related projects:
we want to create a welcoming and friendly environment.
Harassment of participants or other unethical and unprofessional behavior will not be tolerated in our spaces.
The [Contributor Covenant ](http://contributor-covenant.org/version/1/3/0/ )
applies to all projects under the Leaflet organization.
Report any issues to agafonkin@gmail.com.
2012-10-10 23:07:07 +08:00
## Thank You
2014-12-18 10:03:58 +08:00
Not only does your contribution to Leaflet and its community earn our gratitude, but it also makes you AWESOME.
2013-01-11 19:42:15 +08:00
Join [this approved list of awesome people ](https://github.com/Leaflet/Leaflet/graphs/contributors )
2012-11-15 19:58:09 +08:00
and help us push the limits of what's possible with online maps!
