Add Developer Guide
Éric Lemoine
220
Developer-Guide.md
Normal file
220
Developer-Guide.md
Normal file
@@ -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 <target>
|
||||
|
||||
where `<target>` 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
|
||||
<http://localhost:8000/examples/side-by-side.html>.
|
||||
|
||||
You can turn off compilation by appending `?mode=RAW` to the URL, for example
|
||||
<http://localhost:8000/examples/side-by-side.html?mode=RAW>. (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/<branch_name>/`, where `<branch_name>` is the name of the local
|
||||
checked out Git branch. You can now open the examples index page in the
|
||||
browser, for example: <http://localhost:8000/build/gh-pages/master/examples/>.
|
||||
|
||||
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. <http://localhost:8000/test/ol.html>), 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=<example_name>` 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=<example_name>` 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.
|
||||
Reference in New Issue
Block a user