diff --git a/Developer-Guide.md b/Developer-Guide.md new file mode 100644 index 0000000..0710a67 --- /dev/null +++ b/Developer-Guide.md @@ -0,0 +1,220 @@ +# Developer Guide + +Thanks for your interest in contributing to OpenLayers 3 development. Our +preferred means of receiving contributions is through [pull +requests](https://help.github.com/articles/using-pull-requests). + +This page describes what you need to know to contribute code to ol3 as +a developer. + +## Contributor License Agreement + +Before accepting a contribution, we ask that you provide us a Contributor +License Agreement. If you are making your contribution as part of work for +your employer, please follow the guidelines on submitting a [Corporate +Contributor License Agreement](http://www.openlayers.org/ccla.txt). If you are +making your contribution as an individual, you can submit a digital [Individual +Contributor License Agreement](https://docs.google.com/spreadsheet/viewform?formkey=dGNNVUJEMXF2dERTU0FXM3JjNVBQblE6MQ). + +## Setting up development environment + +You will obviously start by +[forking](https://github.com/openlayers/ol3/fork_select) the ol3 repository. + +### Development dependencies + +The minimum requirements are: + +* Git +* Python 2.6 or 2.7 +* Java 7 (JRE and JDK) +* [PhamtomJS](http://phantomjs.org/) 1.6 or higher +* [Closure Linter](https://developers.google.com/closure/utilities/docs/linter_howto) + +The executables `git`, `gjslint`, `java`, `jar`, `python`, and `phamtomjs` +should be in your `PATH`. + +Optionally, you can also install JSDoc 3, version 3.1.1. Installing JSDoc 3 is +necessary if you want to run the full integration suite. + +To get JSDoc 3.1.1 from GitHub: + + $ git clone git://github.com/jsdoc3/jsdoc.git + $ cd jsdoc + $ git checkout v3.1.1 + +Again, the `jsdoc` executable, located at the root of `jsdoc` repository, +should be in your `PATH`. + +### Travis CI + +Although not mandatory it is recommended to set up Travis CI for your ol3 fork. +For that go to your ol3 fork's Service Hooks page and set up the Travis hook. + +## Working with the build tool + +As an ol3 developer you will need to use the `build.py` Python script. This is +the script to use to run the linter, the compiler, the tests, etc. + +The `build.py` script is equivalent to a Makefile. It is actually based on +[pake](https://github.com/twpayne/pake/), which is a simple implementation of +`make` in Python. + +The usage of the script is: + + $ ./build.py + +where `` is the name of the build target you want to execute. For +example: + + $ ./build.py test + +The main build targets are `server`, `lint`, `build`, `test`, and `check`. The +latter is a meta-target that basically runs `lint`, `build`, and `test`. + +The `serve` target starts the [Plovr](http://plovr.com/) web server. You'll +need to start the Plovr server for running the examples and the tests. More +information on that further down. + +Other targets include `doc` and `integration-test`. The latter is the target +used on Travis CI. See ol3's [Travis configuration file](.travis.yml). + +## Running the `check` target + +The `check` target is to be run before pushing code to GitHub and opening pull +requests. Branches that don't pass `check` won't pass the integration tests, +and have therefore no chance of being merged into `master`. The `check` target +runs the tests, so it requires that the Plovr server run. + +To start the Plovr web server use: + + $ ./build.py serve + +To run the `check` target use: + + $ ./build.py check + + +## Running examples + +To run the examples you first need to start the Plovr web server: + + $ ./build.py serve + +Then, either open one of the example html files from the `examples` directory +directly in your browser, or start a simple web server, for example: + + $ python -mSimpleHTTPServer + +and explore the `examples/` directory, for example by opening +. + +You can turn off compilation by appending `?mode=RAW` to the URL, for example +. (By default mode +is `ADVANCED`.) + +Run examples without Plovr: + +The examples can also be run against the `ol.js` standalone lib, without Plovr, +just like the examples +[hosted](http://openlayers.github.com/ol3/master/examples/) on GitHub. Start by +executing the `hostexamples` build target: + + $ ./build.py hostexamples + +This will build `ol.js`, `ol-simple.js`, `ol-whitespace.js`, and `ol.css`, +create the examples index page, and copy everything to +`build/gh-pages//`, where `` is the name of the local +checked out Git branch. You can now open the examples index page in the +browser, for example: . + +To make an example use `ol-simple.js` or `ol-whitespace.js` instead of `ol.js` +append `?mode=simple` or `?mode=whitespace` to the example URL. And append +`?mode=debug` or `?mode=raw` to make the example work in full debug mode. + +## Running tests + +Run the Plovr web server (see above), and either open the `test/ol.html` file +in the browser (e.g. ), or run `./build.py +test` on the console (headless testing with PhantomJS, make sure to install it +first from http://phantomjs.org/download.html). + +See also the test-specific [README](test/README.md). + +## Running the integration tests + +When you submit a pull request the [Travis continuous integration +server](https://travis-ci.org/) will run a full suite of tests, including +building all versions of the library and checking that all of the examples +work. You will receive an email with the results, and the status will be +displayed in the pull request. If you want to run the integration tests +locally, then you'll need to make sure that Plovr is running if it isn't +already, and then start the tests: + + $ ./build.py integration-test + +Running the full suite of integration tests currently takes 5-10 minutes. + +This makes sure that your commit won't break the build. It also runs JSDoc3 to +make sure that there are no invalid API doc directives. + +## Adding examples + +Adding functionality often implies adding one or several examples. This +section provides explanations related to adding examples. + +The examples are located in the `examples` directory. Adding a new example +implies creating two files in this directory, an `.html` file and a `.js` file. +See `examples/simplae.html` and `examples/simple.js` for instance. + +The `.html` file needs to include a script tag with +`loader.js?id=` as its `src`. For example, if the two files for +the example are `myexample.js` and `myexample.html` then the script tag's `src` +should be set to `myexample`. + +You can use `simple.js` and `simple.html` as templates for new examples. + +`build.py serve` should be stopped and restarted for the +`loader.js?id=` script tag to refer to a valid URL. `build.py +serve` triggers the `examples` target which creates a Plovr JSON file for each +example. + +### Use of the `goog` namespace + +Short story: the OL3 examples should not use the `goog` namespace, except +for `goog.require`. + +Longer story: we want that the OL3 examples work in multiple modes: with the +standalone lib (which has implications of the symbols and properties we +export), with Plovr in ADVANCED mode, and with Plovr in RAW (debug) mode. + +Running the examples with Plovr makes it mandatory to declare dependencies with +`goog.require` statements. And for the examples to also run with the standalone +lib we [export](https://github.com/openlayers/ol3/blob/master/src/goog.exports) +`goog.require` as the null function. + +Exporting `goog.require` has a side effect: it adds the `goog` namespace object +to the global object. This is why we can, for example, have `if (goog.DEBUG)` +statements in the code of the examples. + +## Writing good commit messages + +We follow http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +for the formatting of commit messages. + +Basically, here's what a Git commit message should look like: + + Header line: explaining the commit in one line + + Body of commit message is a few lines of text, explaining things + in more detail, possibly giving some background about the issue + being fixed, etc etc. + + The body of the commit message can be several paragraphs, and + please do proper word-wrap and keep columns shorter than about + 74 characters or so. That way "git log" will show things + nicely even when it's indented. + + Further paragraphs come after blank lines. + +Please keep the header line short, no more than 50 characters.