Skip to content

Commit

Permalink
Update README and CONTRIBUTING
Browse files Browse the repository at this point in the history
[ci skip]
  • Loading branch information
elemoine committed Mar 22, 2013
1 parent 3d87ecd commit 6d1fff6
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 218 deletions.
98 changes: 17 additions & 81 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,85 +1,21 @@
# Contributing to OpenLayers
# Contributing to OpenLayers 3

Thanks for your interest in contributing to OpenLayers development. Our
preferred means of receiving contributions is through [pull
requests](https://help.github.com/articles/using-pull-requests).

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).

## Coding guidelines

### Formatting

We use the [Closure
Linter](https://developers.google.com/closure/utilities/docs/linter_howto) to
check source files for potential syntax and coding style issues. To execute the
linter run the following after making your changes:

$ ./build.py lint

This command assumes that the `gjslint` command in on your PATH.

### Compilation

The OpenLayers 3 is compiled and type-checked using the [Closure
Compiler](https://developers.google.com/closure/compiler/). To
compile the code use:

$ ./build.py build-all

### Documentation

We use [jsdoc3](https://github.com/jsdoc3/jsdoc) to generate the API
documentation. To ensure that your changes are properly documented (and don't
break API doc generation), run the following:

$ ./build.py doc

This command assumes that the `jsdoc` command is on your PATH.
Thanks for your interest in contributing to OpenLayers 3.

### Testing
## Contributing Code

Any modifications must not break existing tests. We use
[PhantomJS](http://phantomjs.org/) to run tests *headlessly*.
Use the following to run the tests:

$ ./build.py test

This command assumes that the `phantomjs` command is on your PATH and that the
polvr web server is running (`./build.py serve`).

### The `precommit` target

The Makefile includes a `precommit` target for running all of the
above (`lint`, `build-all`, `doc`, and `test`). As the name of the
target suggests `./build.py precommit` is the command to run before
committing:

$ ./build.py precommit

### 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.
Our preferred means of receiving contributions is through [pull
requests](https://help.github.com/articles/using-pull-requests).

Please keep the header line short, no more than 50 characters.
See the [Developer
Guide](https://github.com/openlayers/ol3/wiki/Developer-Guide) to get started
with OpenLayers 3 development. This guide provides information you should know
before creating pull requests.

Note that, 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).
141 changes: 4 additions & 137 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,141 +2,8 @@

[![Travis CI Status](https://secure.travis-ci.org/openlayers/ol3.png)](http://travis-ci.org/#!/openlayers/ol3)

Welcome to OpenLayers 3!

## Hosted Examples

The examples are hosted on GitHub (as GitHub pages): http://openlayers.github.com/ol3/master/examples/.

By default the examples use the `ol.js` script, which is compiled using Closure
Compiler's ADVANCED mode. By appending `?mode=simple` or `?mode=whitespace` to
the URL you can make the example page load the `ol-simple.js` or
`ol-whitespace.js` builds instead of `ol.js`. As their names suggest it,
`ol-simple.js` and `ol-whitespace.js` are compiled using the SIMPLE and
WHITESPACE modes, respectively. And by appending `?mode=debug` or `?mode=raw`
you will make the example work in full debug mode.

For example:
http://openlayers.github.com/ol3/master/examples/full-screen.html?mode=simple.

## Build OpenLayers 3

Run build.py:

$ ./build.py

Windows users should run `build` instead.

## Run Examples locally

Run the [Plovr](http://plovr.com/) web server with:

$ ./build.py serve

Windows users should run `build serve` instead.

Then, either open one of the example html files from the `examples` directory directly in your browser, or start a simple webserver, 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.

## Run 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).

## Run the linter

First, install the [Closure
Linter](https://developers.google.com/closure/utilities/docs/linter_howto).
Then:

$ ./build.py lint

## Run the check hook before pushing a commit

$ ./build.py check

The check hook does a few quick tests to make sure that the basics still work. This includes:

* Running the linter
* Building the library
* Running the tests


## Continuous 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.

## Add 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/full-screen.html` and `examples/full-screen.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`.

`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.

A note on the use of the `goog` namespace in the examples:

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.
To see OpenLayers 3 in action you can look at the live examples on
http://openlayers.github.com/ol3/master/examples/. If you want to contribute
to OpenLayers 3 please read the [CONTRIBUTING](CONTRIBUTING.md) page.

0 comments on commit 6d1fff6

Please sign in to comment.