-
Notifications
You must be signed in to change notification settings - Fork 0
Developer Guide
Thanks for your interest in contributing to OpenLayers 3 development. Our preferred means of receiving contributions is through pull requests.
This page describes what you need to know to contribute code to ol3 as a developer.
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. If you are making your contribution as an individual, you can submit a digital Individual Contributor License Agreement.
You will obviously start by forking the ol3 repository.
The minimum requirements are:
- Git
- Python 2.6 or 2.7
- Java 7 (JRE and JDK)
- PhamtomJS 1.6 or higher
- Closure Linter
The executables git, gjslint, java, jar, python, and phamtomjs
should be in your PATH.
Optionally, you can also install JSDoc 3. Installing JSDoc 3 is necessary if you want to run the full integration suite.
To get JSDoc from GitHub:
$ git clone git://github.com/jsdoc3/jsdoc.git
Again, the jsdoc executable, located at the root of jsdoc repository,
should be in your PATH.
If you are want to modify the WebGL shaders, you'll need glsl-unit. Get it with git:
$ git clone https://code.google.com/p/glsl-unit/ build/glsl-unit
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.
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. Windows users
can use build.cmd which is a thin wrapper around build.py.
The build.py script is equivalent to a Makefile. It is actually based on
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 serve, lint, build, test, and check. The
latter is a meta-target that basically runs lint, build, and test.
The serve target starts the Plovr 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.
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
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 on GitHub. Start by
executing the host-examples build target:
$ ./build.py host-examples
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.
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.
When you submit a pull request the Travis continuous integration server 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 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/simple.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.
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
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.
We follow http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html for the formatting of commit messages.
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.