From e2da07d4493ac21c764a7fcb14fd1f2ca5f34490 Mon Sep 17 00:00:00 2001 From: tschaub Date: Mon, 22 Dec 2014 12:23:46 -0800 Subject: [PATCH] Updated Release Procedure (markdown) --- Release-Procedure.md | 79 +++++++++++++++++++++++++++++++------------- 1 file changed, 56 insertions(+), 23 deletions(-) diff --git a/Release-Procedure.md b/Release-Procedure.md index 2cfea56..237e604 100644 --- a/Release-Procedure.md +++ b/Release-Procedure.md @@ -1,14 +1,57 @@ This document is a work in progress. When it is finalized, it should be included as a doc within the repository itself. +### Create a release branch + +The release process involves a couple changes to the repository: updating the version number in package.json and adding a changelog. In order to make these release-related changes, create a branch. Note that all the examples below use 3.1.0 as the release version (and 3.0.0 as the previous release). You'll want to use the appropriate version numbers for the release you're working toward. + + git checkout -b release-v3.1.0 master + +### Create a changelog + +Create a changelog for all merges to master since the previous release (see the note below about a potential [race condition](#race-condition) here). You'll want to create a log for all changes since the previous release and name the resulting file like the target release. + + ./tasks/changelog.sh v3.0.0.. >> changelog/v3.1.0.md + +Edit the resulting changelog file with any summary notes or special upgrade considerations. + + git add changelog/v3.1.0.md + git commit -m 'Changelog for v3.1.0' + +### Update `package.json` + +Update the version number in `package.json` to reflect the target release. Create a commit for this change as well. + +E.g. +```json +{ + "name": "openlayers", + "version": "3.1.0", + // ... +} +``` + + git add package.json + git commit -m 'Update package version to 3.1.0' + +### Merge the release branch + +Create a pull request and merge the release branch. This allows for any final review of upgrade notes or other parts of the changelog. + ### Tag Tag the release. In a working copy of the openlayers/ol3 repo: # tag the latest from openlayers/master - git tag -a v3.0.0-beta.3 -m 'v3.0.0-beta.3' + git tag -a v3.1.0 -m '3.1.0' # push the tag - git push --tags origin + git push --tags openlayers + +### Publish to npm + +Run the `publish.sh` task with the version number as specified in the `package.json` (without the "v" prefix). The `publish.sh` script makes sure that the tag name and the version in `package.json` for that tag match. + + ./tasks/publish.sh 3.1.0 ### Update website @@ -16,17 +59,17 @@ You need a local clone of the openlayers/openlayers.github.io repo, with the `bu First of all make sure your `build` branch is up-to-dat: - git fetch origin - git merge --ff-only origin/build + git fetch openlayers + git merge --ff-only openlayers/build Edit the `src/pages/index.hbs` page to link to the latest release (this will not be a working link until the release page is added below). Commit and push the change: # commit the change git add src/pages/index.hbs - git commit -m 'Updating for v3.0.0-beta.3' + git commit -m 'Updating for v3.1.0' # push to GitHub - git push origin build + git push openlayers build Publish the release artifacts (examples and source) on the website. In a working copy of the openlayers/openlayers.github.io: @@ -34,7 +77,7 @@ Publish the release artifacts (examples and source) on the website. In a workin npm install # publish - treeish=v3.0.0-beta.3 npm run deploy + treeish=v3.1.0 npm run deploy ### Create release page and post archive for download @@ -42,25 +85,15 @@ Create an archive from the artifacts created by the `npm run deploy` step above. # from your working copy of the openlayers/openlayers.github.io repo cd .grunt/openlayers-website/dist/en/ - zip -r v3.0.0-beta.3.zip v3.0.0-beta.3/ + zip -r v3.1.0.zip v3.1.0/ Note: we do not rely on the archive created by GitHub because it only contains the source code. Our archive includes the ol builds, the hosted examples, the generated API docs, etc. -Edit the GitHub release page for the tag to include a log of changes since the last release. GitHub release page: https://github.com/openlayers/ol3/releases/new?tag=v3.0.0-beta.3 (do not forget to change the `tag` value in the URL). - -Create the change log with: https://github.com/tschaub/github-changelog. For example: - - sudo npm install -g github-changelog - gh-changelog --merged --owner openlayers --repo ol3 --since 2014-04-07 > changelog.md - -Alternative method on Linux: - - git log --merges --abbrev-commit --format=format:'* %s %b - %an' v3.0.0-beta.2..v3.0.0-beta.3 | sed -r 's/Merge pull request (#[0-9]+) from \S* /\1 /' > /tmp/changelog - -Alternative method on OSX: - - git log --merges --abbrev-commit --format=format:'* %s %b - %an' v3.0.0-beta.2..v3.0.0-beta.3 | sed -E 's/Merge pull request (#[0-9]+) from \S* /\1 /' > /tmp/changelog +Edit the GitHub release page for the tag to include the Markdown from the changelog created above. Attach the `.zip` archive created above to the release page. - \ No newline at end of file +### Notes + + +Note that there is a potential race condition related to creating a changelog before a release is tagged. This could be avoided by generating the changelog after tagging the release. However, since we already need to make a change to the repository for the release (updating the version in package.json), the changelog creation step is included with this change for convenience. There aren't serious consequences associated with missing an entry in the changelog, so this should be an acceptable tradeoff.