diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b342e3b0b..03a0a402d5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 +Thanks for your interest in contributing to OpenLayers 3. + +## Contributing Code + +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). +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. -## 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. +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). diff --git a/README.md b/README.md index ff283db5e9..0a3a4c44e3 100644 --- a/README.md +++ b/README.md @@ -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 -. - -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. - -## Run 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). - -## 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=` 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=` 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.