Release process

1. Prepare the release commit

1. Ensure all relevant PRs have merged to develop.
2. Create release branch based off latest develop. Use SemVer to come up with the next version number: [major].[minor].[patch] (all three numbers are required).

   git checkout develop
   git pull
   git checkout -b release/[version number]

3. Update the root package.jsonversion (match core's next version, or bump a patch version if core wasn't changed).
4. Commit the changes.

   git commit -a -m "Prepare release v[version number]"

5. Create a PR. This PR will be very small, maybe only one line.

2. Review the release PR

A useful way to determine exactly what happened in a release is to diff the commits with a recent release tag or use the relevant milestone.

1. After creating the PR, write release notes in the PR description.
2. Perform a regression pass on the release preview artifacts.
   • Push small fixes to the release PR. Larger fixes may warrant their own PRs.
3. Merge the release PR.

3. Publish to NPM

1. Ensure you're on the latest develop branch (with merged release PR).
2. Run $(npm bin)/lerna publish --skip-npm --scope '@blueprintjs/{pkgs,to,publish}', fill out the glob as necessary.
3. Interactively pick version numbers.
4. Review the commit which Lerna just produced.
   • If there are blocking issues, you should delete the commit (reset HEAD^) and delete any tags that were created.
5. Push to develop with tags: git push origin develop --follow-tags.
6. Attach release notes to the new tags which were produced in the Github UI.

4. Update documentation site

1. After publishing to NPM, run yarn compile and yarn dist on develop.
2. Run a local web server from the root of the docs/ folder and do a quick spot check to make sure the static assets got built correctly with the updated release versions.
3. Run yarn deploy to push changes to the live site hosted on the master branch.

Bonus: Pre-releases @next

Simply run the lerna publish command on the next branch instead of on develop. The Circle publish script will detect the next branch publish to the @next npm dist-tag.

Bonus: Releasing a previous major version

The main branch of this repository contains latest code. Making a 1.x or 2.x release is similar to the process above (target release/1.x instead of develop), but the docs deployment part is different:

• In the following steps, replace 1.x with the appropriate major version
• Checkout release/1.x and yarn to re-install depenendencies
• Build fresh 1.x docs with yarn clean && yarn compile && yarn dist
• Copy the git-ignored docs/docs/ (note the nested folder path!) folder outside the repo.
• Switch to develop, start a new branch.
• Paste the contents of the folder you just copied into docs-static/docs/v1/. Replace all existing contents of the folder (there will be old files with md5-hashed names that are now dead code).
• Make a PR against develop with the changes to the static assets you just made.

Writing release notes

See other releases for example format. We typically describe changes using the following groups:

1. 🔥 BREAKING
2. NEW
3. Fixed
4. Changed
5. Deprecated

A 🌟 is used to indicate release highlights: features or fixes of particular note.