Created standard bench interface

.gitignore

@@ -2,10 +2,9 @@
 /_site
 /dist/mapbox-gl-dev.js
 /dist/mapbox-gl.js
-/dist/mapbox-gl.js.map
+*.js.map
 /node_modules
 npm-debug.log
 *.sublime-*
 coverage
 .DS_Store
-/bench/buffer/buffer_benchmark.js.map

README.md

@@ -90,6 +90,10 @@ There are two test suites associated with Mapbox GL JS
  - `npm test` runs quick unit tests
  - `npm run test-suite` runs slower rendering tests from the [mapbox-gl-test-suite](https://github.com/mapbox/mapbox-gl-test-suite) repository
 
+ ### Running Benchmarks
+
+See [`bench/README.md`](https://github.com/mapbox/mapbox-gl-js/blob/master/bench/README.md).
+
 ### Running the FPS Benchmark
 
 The FPS benchmarking page compares the performance of your local copy of GL JS against previously released versions. Benchmarking configuration is within `bench/fps/site.js`.
@@ -103,7 +107,7 @@ $ open "http://localhost:9966/bench/fps/?access_token="`echo $MapboxAccessToken`
 
 ### Writing Documentation
 
-See [docs/README.md](https://github.com/mapbox/mapbox-gl-js/blob/master/docs/README.md).
+See [`docs/README.md`](https://github.com/mapbox/mapbox-gl-js/blob/master/docs/README.md).
 
 ### Recommended Reading
 

bench/README.md

@@ -0,0 +1,86 @@
+# Benchmarks
+
+Benchmarks help us catch performance regressions and improve performance.
+
+## Running a Benchmark
+
+Start the benchmark server
+
+```bash
+npm run start-bench
+```
+
+Open the benchmark runner
+
+ - [buffer benchmark](http://localhost:6699/bench/?benchmark=buffer)
+
+## Writing a Benchmark
+
+Good benchmarks
+
+ - are precise (i.e. running the test multiple times returns roughly the same result)
+ - operate in a way that mimics real-world usage
+ - use large, diverse, real-world data
+ - are conceptually simple
+
+Benchmarks are implemented as a function that returns an instance of `Evented`.
+
+```js
+runBenchmark(options: { accessToken: string; }): Evented
+```
+
+The instance of `Evented` may fire any number of `log` and `error` events. The
+instance of `Evented` must fire exactly one `end` event.
+
+### `log`
+
+Fire the `log` event to report benchmark progress to the user.
+
+```js
+{
+    message: string;
+    color: string = 'blue'; // name of a Mapbox base color https://mapbox.com/base/styling/color
+}
+```
+
+If your benchmark has a notion of running multiple "samples", you might emit
+one `log` event per sample.
+
+```js
+benchmark.fire('log', {
+    message: 'Finished sample ' + i + ' in ' + formatNumber(time) + ' ms'
+});
+```
+
+These events have no machine-semantic meaning.
+
+### `end`
+
+Fire the `end` event to indicate the benchmark has finished running and report
+its results.
+
+These events have both human-readable results (`message`) and machine-readable results (`score`). Smaller `score`s are "better."
+
+```js
+{
+    message: string;
+    score: number;
+}
+```
+
+```js
+benchmark.fire('end', {
+    message: 'Average time is ' + formatNumber(averageTime)) + 'ms',
+    score: averageTime
+});
+```
+
+### `error`
+
+Fire the `error` event to indicate the benchmark has encountered a fatal error.
+
+```js
+{
+    error: Error;
+}
+```