From 313e313f7a2a6d1cc8b58da71be97d52e09c600b Mon Sep 17 00:00:00 2001 From: Peter Robins Date: Mon, 14 Jul 2014 11:13:05 +0000 Subject: [PATCH] Move developer guide from wiki to CONTRIBUTING.md --- CONTRIBUTING.md | 313 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 301 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03a0a402d5..7bb9bea8b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,18 +4,307 @@ 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). +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). Make sure +that your pull request follows our pull request guidelines below before submitting it. -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. +This page describes what you need to know to contribute code to ol3 as a developer. -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 + +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](https://raw.github.com/openlayers/cla/master/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). +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. + +### Travis CI + +The Travis CI hook is enabled on the Github repository. This means every pull request +is run through a full test suite to ensure it compiles and passes the tests. Failing +pull requests will not be merged. + +Although not mandatory, it is also 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. +Then every time you push to your fork, the test suite will be run. This means +errors can be caught before creating a pull request. For those making +small or occasional contributions, this may be enough to check that your contributions +are ok; in this case, you do not need to install the build tools on your local environment +as described below. + +### Development dependencies + +The minimum requirements are: + +* Git +* [Node.js](http://nodejs.org/) +* Python 2.6 or 2.7 with a couple of extra modules (see below) +* Java 7 (JRE and JDK) + +The executables `git`, `java`, `jar`, and `python` should be in your `PATH`. + +You can check your configuration by running: + + $ ./build.py checkdeps + +To install the Node.js dependencies run + + $ npm install + +To install the extra Python modules, run: + + $ sudo pip install -r requirements.txt +or + + $ cat requirements.txt | sudo xargs easy_install + +depending on your OS and Python installation. + +## 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. 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](https://github.com/twpayne/pake/), which is a simple implementation of +`make` in Python. + +The usage of the script is: + + $ ./build.py + +where `` 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 a node-based web server, which we will refer to as the *dev server*. You'll need to start that server for running the examples and the tests in a browser. More information on that further down. + +Other targets include `apidoc` and `ci`. The latter is the target used on Travis CI. See ol3's [Travis configuration file](https://github.com/openlayers/ol3/blob/master/.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`. + +To run the `check` target: + + $ ./build.py check + +If you want to run the full suite of integration tests, see "Running the integration +tests" below. + +## Running examples + +To run the examples you first need to start the dev server: + + $ ./build.py serve + +Then, just point your browser in your browser. For example . + +Run examples against the `ol.js` standalone build: + +The examples can also be run against the `ol.js` standalone lib, just like the examples +[hosted](http://openlayers.github.com/ol3/master/examples/) on GitHub. Start by +executing the `host-examples` build target: + + $ ./build.py host-examples + +After running `host-examples` you can now open the examples index page in the browser, for example: . (This assumes that the `hosted` directory is a web directory, served by Apache 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. + +Append `?mode=debug` or `?mode=raw` to make the example work in full debug mode. In +full debug mode the OpenLayers and Closure Library scripts are loaded individually by +the Closure Library's `base.js` script (which the example page loads and +executes before any other script). + +## Running tests + +To run the tests in a browser start the dev server (`./build.py serve`) and open in the browser. + +To run the tests on the console (headless testing with PhantomJS) use the `test` target: + + $ ./build.py test + +See also the test-specific [README](../blob/master/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. + +To run the full suite of integration tests use the `ci` target: + + $ ./build.py ci + +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/simple.html` and `examples/simple.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`. + +You can use `simple.js` and `simple.html` as templates for new examples. + +### Use of the `goog` namespace in 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), and compiled together with the ol3 library. + +Compiling the examples together with the library makes it mandatory to declare dependencies with `goog.require` statements. + +## Pull request guidelines + +Your pull request must: + + * Follow OpenLayers 3's coding style. + + * Pass the integration tests run automatically by the Travis Continuous + Integration system. + + * Address a single issue or add a single item of functionality. + + * Contain a clean history of small, incremental, logically separate commits, + with no merge commits. + + * Use clear commit messages. + + * Be possible to merge automatically. + + +### The `check` build target + +It is strongly recommended that you run + + $ ./build.py check + +before every commit. This will catch many problems quickly, and it is much +faster than waiting for the Travis CI integration tests to run. + +The `check` build target runs a number of quick tests on your code. These +include: + + * Lint + * Compile + * Tests + + +### Follow OpenLayers 3's coding style + +OpenLayers 3 follows [Google's JavaScript Style +Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml). +This is checked using the [Closure +Linter](https://developers.google.com/closure/utilities/) in strict mode. You +can run the linter locally on your machine before committing using the `lint` +target to `build.py`: + + $ ./build.py lint + +In addition to fixing problems identified by the linter, please also follow the +style of the existing OpenLayers 3 code, which includes: + + * Always wrap the body of `for`, `if`, and `while` statements in braces. + + * Class methods should be in alphabetical order. + + * `var` declarations should not span multiple lines. If you cannot fit all + the declarations in a single line, then start a new `var` declaration on a + new line. Within a single line, variables should be declared in + alphabetical order. + + * Do not use assignments inside expressions. + + +### Pass the integration tests run automatically by the Travis CI system + +The integration tests contain a number of automated checks to ensure that the +code follows the OpenLayers 3 style and does not break tests or examples. You +can run the integration tests locally using the `ci` target: + + $ ./build.py ci + + +### Address a single issue or add a single item of functionality + +Please submit separate pull requests for separate issues. This allows each to +be reviewed on its own merits. + + +### Contain a clean history of small, incremental, logically separate commits, with no merge commits + +The commit history explains to the reviewer the series of modifications to the +code that you have made and breaks the overall contribution into a series of +easily-understandable chunks. Any individual commit should not add more than +one new class or one new function. Do not submit commits that change thousands +of lines or that contain more than one distinct logical change. Trivial +commits, e.g. to fix lint errors, should be merged into the commit that +introduced the error. See the [Atomic Commit Convention on Wikipedia](http://en.wikipedia.org/wiki/Atomic_commit#Atomic_Commit_Convention) for more detail. + +`git apply --patch` and `git rebase` can help you create a clean commit +history. +[Reviewboard.org](http://www.reviewboard.org/docs/codebase/dev/git/clean-commits/) +and [Pro GIT](http://git-scm.com/book/en/Git-Tools-Rewriting-History) have +explain how to use them. + + +### Use clear commit messages + +Commit messages should be short, begin with a verb in the imperative, and +contain no trailing punctuation. 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. + +### Be possible to merge automatically + +Occasionally other changes to `master` might mean that your pull request cannot +be merged automatically. In this case you may need to rebase your branch on a +more recent `master`, resolve any conflicts, and `git push --force` to update +your branch so that it can be merged automatically. \ No newline at end of file