Skip to content

Latest commit

 

History

History
199 lines (144 loc) · 9.89 KB

CONTRIBUTING.md

File metadata and controls

199 lines (144 loc) · 9.89 KB
Raw

Contributing to Leaflet

  1. Getting Involved
  2. Reporting Bugs
  3. Contributing Code
  4. Running the Tests
  5. Improving Documentation
  6. Code of Conduct
  7. Thank You

Getting Involved

Third-party patches are absolutely essential in our quest to create the best mapping library that will ever exist. However, they're not the only way to get involved with Leaflet development. You can help the project tremendously by discovering and reporting bugs; improving documentation; helping others on Stack Overflow, GIS Stack Exchange and GitHub issues; tweeting to @LeafletJS; and spreading the word about Leaflet among your colleagues and friends.

Reporting Bugs

Before reporting a bug on the project's issues page, 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.

After you've made sure that you've found a new Leaflet bug, here are some tips for creating a helpful report that will make fixing it much easier and quicker:

  • Write a descriptive, specific title. Bad: Problem with polylines. Good: Doing X in IE9 causes Z.
  • Include browser, OS and Leaflet version info in the description.
  • Create a simple test case that demonstrates the bug (e.g. using Leaflet plunker).
  • Check whether the bug can be reproduced in other browsers.
  • Check if the bug occurs in the stable version, main, or both.
  • Bonus tip: if the bug only appears in the main version but the stable version is fine, use git bisect to find the exact commit that introduced the bug.

If you just want some help with your project, try asking on Stack Overflow or GIS Stack Exchange instead.

Contributing Code

Considerations for Accepting Patches

While we happily accept patches, we're also committed to keeping Leaflet simple, lightweight and blazingly fast. So bugfixes, performance optimizations and small improvements that don't add a lot of code are much more likely to get accepted quickly.

Before sending a pull request with a new feature, check if it's been discussed before already on GitHub issues and ask yourself two questions:

  1. Are you sure that this new feature is important enough to justify its presence in the Leaflet core? Or will it look better as a plugin in a separate repository?
  2. Is it written in a simple, concise way that doesn't add bulk to the codebase?

If your feature or API improvement did get merged into main, please consider submitting another pull request with the corresponding documentation update.

Setting up the Build System

The Leaflet build system uses NodeJS. To set up the Leaflet build system, install NodeJS. Then run the following commands in the project root to install dependencies:

npm install

or, if you prefer yarn over npm:

yarn install

Making Changes to Leaflet Source

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 on the GitHub Help website — it will get you started quickly.

You should always write each batch of changes (feature, bugfix, etc.) in its own topic branch. Please do not commit to the main branch of your fork — otherwise your unrelated changes will go into the same pull request.

You should also follow the code style and whitespace conventions of the original codebase. In particular, use tabs for indentation and spaces for alignment.

Before committing your changes, run npm run lint to catch any JS errors in the code and fix them. The same command is automatically executed while committing. You can prevent it from execution with the git flag --no-verify: git commit -m "WIP" --no-verify.

Also, please make sure that you have line endings configured properly in Git! Otherwise the diff will show that all lines of a file were changed even if you touched only one.

Happy coding!

Building Leaflet

The source JavaScript code for Leaflet is a few dozen files, in the src/ directory. But normally, Leaflet is loaded in a web browser as just one JavaScript file.

In order to create this file, run npm run build or yarn run build.

You'll find dist/leaflet-src.js and dist/leaflet.js. The difference is that dist/leaflet-src.js has sourcemaps and it's not uglified, so it's better for development. dist/leaflet.js is uglified and thus is smaller, so it's better for deployment.

When developing (or bugfixing) core Leaflet functionalities, it's common to use the webpages in the debug/ directory, and run the tests in a graphical browser. This requires regenerating the bundled files quickly.

In order to do so, run npm run watch or yarn run watch. This will keep on rebuilding the bundles whenever any source file changes.

Running the Tests

Before running the tests make sure that the source code has been built (as mentioned above). If you want to run the tests in the background while working on Leaflet it is recommended you run the build in watch mode. This way the tests will automatically re-run when changes to the source code are made.

To run the tests from the command line, ensure you have Google Chrome installed and then run:

npm test

By default the tests will run in Google Chrome headlessly (without a UI), to run the tests in other browsers you can pass in the --browsers flag.

npm test -- --browsers Firefox

For a list of available browsers see the documentation of the included launcher plugins:

Improving Documentation

The code of the live Leaflet website that contains all documentation and examples is located in the docs/ directory of the main branch and is automatically generated from a set of HTML and Markdown files by Jekyll.

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: browse the docs/ directory, choose a certain file for editing, click the Edit button, make changes and follow instructions from there. Once it gets merged, the changes will immediately appear on the website.

To work on the documentation locally ensure you have Ruby installed. You can download it from the Ruby website or use rbenv (recommended).

You'll need to install the same Ruby version as specified in .ruby-version. If you are using rbenv you can install this by running rbenv install from the docs/ directory.

If you need to make edits in a local repository to see how it looks in the process, do the following:

  1. Open a terminal in the docs/ directory.
  2. Make sure you are on the main branch by running git checkout main.
  3. Run bundle install to install the dependencies.
  4. Run npm run serve to serve the documentation.
  5. Open http://localhost:4000 in your web browser.

Now any file changes in docs/ will be applied when you reload pages. After committing the changes, just send a pull request.

API documentation

Since Leaflet 1.0.0-rc1, the API documentation in reference-1.0.0.html is handled via 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, make sure that the development dependencies are installed (run either npm install or yarn install), then just run

npm run 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 docs/reference.html - there is no need to send pull requests with changes to this file to update the API documentation.

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 applies to all projects under the Leaflet organization. Report any issues to agafonkin@gmail.com or ivan@sanchezortega.es.

Thank You

Not only does your contribution to Leaflet and its community earn our gratitude, but it also makes you AWESOME. Join this approved list of awesome people and help us push the limits of what's possible with online maps!