diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3028102a53..a34da9cfec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,16 +58,17 @@ as described below. The minimum requirements are: +* GNU Make * Git * [Node.js](http://nodejs.org/) (0.10.x or higher) * 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`. +The executables `git`, `node`, `python` and `java` should be in your `PATH`. You can check your configuration by running: - $ ./build.py checkdeps + $ make check-deps To install the Node.js dependencies run @@ -82,24 +83,22 @@ or depending on your OS and Python installation. +(You can also install the Python modules in a Python virtual environment if you want to.) + ## 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`. +As an ol3 developer you will use `make` to run build targets defined in the +`Makefile` located at the root of the repository. The `Makefile` includes +targets for running the linter, the compiler, the tests, etc. -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 `make` is as follows: -The usage of the script is: - - $ ./build.py + $ make where `` is the name of the build target you want to execute. For example: - $ ./build.py test + $ make 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`. @@ -116,7 +115,7 @@ and have therefore no chance of being merged into `master`. To run the `check` target: - $ ./build.py check + $ make check If you want to run the full suite of integration tests, see "Running the integration tests" below. @@ -125,29 +124,29 @@ tests" below. To run the examples you first need to start the dev server: - $ ./build.py serve + $ make serve -Then, just point your browser in your browser. For example . +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: +The examples can also be run against the `ol.js` standalone build, just like +the examples [hosted](http://openlayers.org/en/master/examples/) on GitHub. +Start by executing the `host-examples` build target: - $ ./build.py host-examples + $ make 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.) +After running `host-examples` you can now open the examples index page in the browser: . (This assumes that you still have the dev server running.) Append `?mode=raw` to make the example work in full debug mode. In raw 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 in a browser start the dev server (`make serve`) and open in the browser. To run the tests on the console (headless testing with PhantomJS) use the `test` target: - $ ./build.py test + $ make test See also the test-specific [README](../master/test/README.md). @@ -161,7 +160,7 @@ displayed in the pull request. To run the full suite of integration tests use the `ci` target: - $ ./build.py ci + $ make ci Running the full suite of integration tests currently takes 5-10 minutes. @@ -174,13 +173,8 @@ 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`. +implies creating two or three files in this directory, an `.html` file, a `.js` +file, and, optionally, a `.css` file. You can use `simple.js` and `simple.html` as templates for new examples. @@ -218,7 +212,7 @@ Your pull request must: It is strongly recommended that you run - $ ./build.py check + $ make 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. @@ -238,9 +232,9 @@ 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`: +target: - $ ./build.py lint + $ make lint In addition to fixing problems identified by the linter, please also follow the style of the existing OpenLayers 3 code, which includes: @@ -279,7 +273,7 @@ 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 + $ make ci ### Address a single issue or add a single item of functionality