Update README and CONTRIBUTING
[ci skip]
This commit is contained in:
Éric Lemoine
@@ -1,85 +1,21 @@
|
|||||||
# Contributing to OpenLayers
|
# Contributing to OpenLayers 3
|
||||||
|
|
||||||
Thanks for your interest in contributing to OpenLayers development. Our
|
Thanks for your interest in contributing to OpenLayers 3.
|
||||||
preferred means of receiving contributions is through [pull
|
|
||||||
|
## Contributing Code
|
||||||
|
|
||||||
|
Our preferred means of receiving contributions is through [pull
|
||||||
requests](https://help.github.com/articles/using-pull-requests).
|
requests](https://help.github.com/articles/using-pull-requests).
|
||||||
|
|
||||||
Before accepting a contribution, we ask that you provide us a Contributor
|
See the [Developer
|
||||||
License Agreement. If you are making your contribution as part of work for
|
Guide](https://github.com/openlayers/ol3/wiki/Developer-Guide) to get started
|
||||||
your employer, please follow the guidelines on submitting a [Corporate
|
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
|
Contributor License Agreement](http://www.openlayers.org/ccla.txt). If you are
|
||||||
making your contribution as an individual, you can submit a digital
|
making your contribution as an individual, you can submit a digital [Individual
|
||||||
[Individual Contributor License Agreement](https://docs.google.com/spreadsheet/viewform?formkey=dGNNVUJEMXF2dERTU0FXM3JjNVBQblE6MQ).
|
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.
|
|
||||||
|
|
||||||
### Testing
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Please keep the header line short, no more than 50 characters.
|
|
||||||
|
|||||||
141
README.md
141
README.md
@@ -2,141 +2,8 @@
|
|||||||
|
|
||||||
[](http://travis-ci.org/#!/openlayers/ol3)
|
[](http://travis-ci.org/#!/openlayers/ol3)
|
||||||
|
|
||||||
|
Welcome to OpenLayers 3!
|
||||||
|
|
||||||
## Hosted 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
|
||||||
The examples are hosted on GitHub (as GitHub pages): http://openlayers.github.com/ol3/master/examples/.
|
to OpenLayers 3 please read the [CONTRIBUTING](CONTRIBUTING.md) page.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user