From 30a749027ce44fb50277927ea00ecd8a7b56c461 Mon Sep 17 00:00:00 2001 From: Lucas Wojciechowski Date: Thu, 28 Jan 2016 10:54:46 -0800 Subject: [PATCH] Create separate RELEASE.md file, update release instructions --- README.md | 15 -------- RELEASE.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 27 +++++++------- package.json | 1 + 4 files changed, 110 insertions(+), 30 deletions(-) create mode 100644 RELEASE.md diff --git a/README.md b/README.md index 472aab6495c..cc737a9ce28 100644 --- a/README.md +++ b/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 diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 00000000000..f15bd80780b --- /dev/null +++ b/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 +``` diff --git a/docs/README.md b/docs/README.md index 07ffb81dec6..d13053578a2 100644 --- a/docs/README.md +++ b/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 diff --git a/package.json b/package.json index 20325bd593b..63882d17033 100644 --- a/package.json +++ b/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",