Release process

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.json version (match core's version, or bump a patch version if core wasn't changed).

4. Commit the changes and create a PR.

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

Review the release PR

1. After creating the PR, write release notes in the PR description.
2. Perform a regression pass on the release preview artifacts.
3. Merge the release PR.

Publish to NPM

1. Run lerna publish --skip-npm --scope '@blueprintjs/{core,datetime,labs,table}' (or some appropriate subset of the packages).
2. Interactively pick version numbers.
3. 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.
4. Push to develop with tags: git push develop --follow-tags.
5. Attach release notes to the new tags which were produced in the Github UI.

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.

Making a 1.x release

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

• Build the 1.x docs with yarn compile-libs && yarn dist on release/1.x.
  • Make sure you have the right node_modules and have run yarn clean at the root to avoid picking up any 2.x built assets).
• 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.

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