Create separate RELEASE.md file, update release instructions

README.md

@@ -76,21 +76,6 @@ $ open "http://localhost:9966/bench/fps/?access_token="`echo $MapboxAccessToken`
 
 See [docs/README.md](https://github.com/mapbox/mapbox-gl-js/blob/master/docs/README.md).
 
-## Releasing
-
-To prepare a release:
-
-* Run `git checkout master && git merge origin/mb-pages` to merge `mb-pages` into `master`
-* Update `CHANGELOG.md` with all changes since the last release. A list of commits is available on the [GitHub Releases page](https://github.com/mapbox/mapbox-gl-js/releases) through a link that says "X commits to master since this release"
-* Update the version number in `package.json`, `README.md`, `bench/fps/site.js`, `_config.yml`, and `_config.mb-pages.yml`
-* Run `git commit -a -m vX.Y.Z` to commit changes
-* Run `git tag vX.Y.Z` to tag the release
-* Run `git push origin && git push origin --tags` to push the new commit and tag to GitHub
-* Create a [GitHub release](https://github.com/mapbox/mapbox-gl-js/releases/new) using the tag you just pushed and the text in `CHANGELOG.md`
-* The [CI server](https://circleci.com/gh/mapbox/mapbox-gl-js) will automatically publish tagged builds to the Mapbox CDN. Wait for this build to finish successfully before proceeding.
-* Run `git checkout mb-pages && git merge master && git push origin mb-pages && git checkout master` to merge `master` into `mb-pages` and publish documentation.
-* Run `npm install && npm publish` to publish the release to npm.
-
 ## [Style Reference](https://www.mapbox.com/mapbox-gl-style-spec/)
 
 ## Recommended Reading

RELEASE.md

@@ -0,0 +1,97 @@
+# Release Procedure
+
+## Check for "Release Blocker" issues or PRs
+
+If there are any [open "Release Blocker" issues or PRs](https://github.com/mapbox/mapbox-gl-js/labels/release%20blocker), we cannot do a release.
+
+## Get the latest `master`
+
+```bash
+git checkout master
+git fetch
+git merge --ff-only origin/master
+```
+
+## Merge `mb-pages` into `master`
+
+```bash
+git merge origin/mb-pages
+```
+
+## Make sure your environment is in a good state
+
+```bash
+npm install
+npm test
+npm run test-suite
+```
+
+## Test examples
+
+Start the docs server by running
+
+```bash
+npm run start-docs
+```
+
+Test at least the following examples before continuing
+
+ - [Add GeoJSON markers](http://127.0.0.1:4000/mapbox-gl-js/example/geojson-markers/)
+ - [Animate a point](http://127.0.0.1:4000/mapbox-gl-js/example/animate-point-along-line/)
+ - [Get features under the mouse pointer](http://127.0.0.1:4000/mapbox-gl-js/example/featuresat/)
+ - [Fly to a location based on scroll position](http://127.0.0.1:4000/mapbox-gl-js/example/scroll-fly-to/)
+ - [Display markers with popups](http://127.0.0.1:4000/mapbox-gl-js/example/marker-popup/)
+ - [Highlight features under the mouse pointer](http://127.0.0.1:4000/mapbox-gl-js/example/hover-styles/)
+ - [Dispay driving directions](http://127.0.0.1:4000/mapbox-gl-js/example/mapbox-gl-directions/)
+ - [Set a point after Geocoder result](http://127.0.0.1:4000/mapbox-gl-js/example/point-from-geocoder-result/)
+
+## Choose version number
+
+Choose a new version number, respecting [semver](http://semver.org/).
+
+## Update `CHANGELOG.md`
+
+Update `CHANGELOG.md` with all changes since the last release. A list of commits is available on the [GitHub Releases page](https://github.com/mapbox/mapbox-gl-js/releases) through a link that says "X commits to master since this release"
+
+## Update version number
+
+Update the version number in `package.json`, `README.md`, `bench/fps/site.js`, `_config.yml`, and `_config.mb-pages.yml`.
+
+## Commit and tag release
+
+After **carefully inspecting the diff**, commit and tag the release. **There is no going back once you execute this command! A published version tag is forever on our CDN.**
+
+```bash
+VERSION=vX.Y.Z # UPDATE ME
+git commit -am $VERSION
+git tag $VERSION
+git push origin --follow-tags
+```
+
+## Create a GitHub release
+
+Create a [GitHub release](https://github.com/mapbox/mapbox-gl-js/releases/new) using the tag you just
+pushed and the text in `CHANGELOG.md`
+
+## Wait for CI server to build successfully
+
+The [CI server](https://circleci.com/gh/mapbox/mapbox-gl-js) will automatically publish tagged builds to the Mapbox CDN. Wait for this build to finish successfully before proceeding.
+
+## Merge `master` into `mb-pages`
+
+Merge `master` into `mb-pages` and publish the updated documentation.
+
+```bash
+git checkout mb-pages
+git merge master
+git push origin mb-pages
+git checkout master
+```
+
+## Publish to npm
+
+Publish the release to npm. **There is no going back once you execute this command! A published npm package is forever.**
+
+```bash
+npm publish
+```

docs/README.md

@@ -28,35 +28,32 @@ In the post body, write the HTML and JavaScript constituting the example.
 * Do **not** use custom styles from your personal account. Use only the default `mapbox` account styles.
 * When embedding literal JSON (GeoJSON or GL style snippets) into script code, double-quote property names and string values. Elsewhere, use single-quoted strings.
 
-## Generating Documentation
-
-To generate new docs, ensure you are running Jekyll version 2.5.x
+## Running Documentation Server Locally
 
+To start a documentation server locally run
 ```bash
-jekyll -v
- > jekyll 2.5.3
+npm run start-docs
 ```
 
-Then run
+You can view the documentation at
 
 ```bash
-npm run docs
+open http://127.0.0.1:4000/mapbox-gl-js
 ```
 
-This will generate a [Jekyll](http://jekyllrb.com) site in the `docs` directory. If this is the first time building the site, you will need to also generate the `dist/mapbox-gl.js`. To generate the dist folder and scripts run
+## Troubleshooting
 
-```bash
-npm run production
-```
-You will only need to do this once. To view the documentation, start a Jekyll server (in the project's root directory)
+Ensure you have the right version of all dependencies
 
 ```bash
-jekyll serve -w
+npm install
 ```
-and open the served page
+
+Ensure you are running Jekyll version 2.5.x
 
 ```bash
-open http://127.0.0.1:4000/mapbox-gl-js
+jekyll -v
+ > jekyll 2.5.3
 ```
 
 ## Branch Usage

package.json

@@ -62,6 +62,7 @@
   "scripts": {
     "start": "budo js/mapbox-gl.js --serve=debug/mapbox-gl.js --live --port 9966 -- --transform --standalone mapboxgl",
     "start-buffer": "budo bench/buffer/buffer_benchmark.js --port 6699 -- --transform unassertify --plugin [minifyify --map /bench/buffer/buffer_benchmark.js.map --output bench/buffer/buffer_benchmark.js.map] --standalone bufferBenchmark",
+    "start-docs": "npm run production && npm run docs && jekyll serve -w",
     "lint": "eslint js test && documentation --lint",
     "test": "npm run lint && prova test/js/*/*.js -q",
     "test-suite": "node test/render.test.js && node test/query.test.js",