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. Commit & tag version bumps with Lerna:

   $ yarn lerna version

3. Interactively pick version numbers.
   • Look at the histories of the different packages (for example, this GitHub URL shows what changed in the datetime package recently) to help with this.
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 a successful publish to NPM, run the following on develop to produce a clean build:

   yarn clean && yarn compile && yarn dist

2. Run yarn site to copy assets and launch a server for the site/ directory.
3. Do a spot check on the server to confirm the site is in order.
4. Run yarn deploy to push changes to the live site hosted on the gh-pages branch.

Bonus: Pre-releases @next

1. Simply run the lerna publish command on the next branch instead of on develop. The Circle publish script will publish from this branch to the @next npm dist-tag.
2. After successfully publishing to NPM, create a PR to merge next back into develop to update the package.json files. Then delete next until next time.

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:

• Checkout release/#.x and yarn to re-install depenendencies
• Build fresh #.x docs with yarn clean && yarn compile && yarn dist
• Replace site/docs/versions/# on develop with the contents of packages/docs-app/dist
  • Copy packages/docs-app/dist/ outside of the repo.
  • Switch to develop, start a new branch.
  • Paste the contents of the folder you just copied into site/docs/versions/#. Replace all existing contents of the folder (there may be old files with md5-hashed names that are now dead code).
  • 🌟 If you maintain multiple clones of Blueprint (say at 1.x and 3.x) then this is very easy:

    rsync --recursive --delete packages/docs-app/dist/ ../blueprint/site/docs/versions/#
    

• 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.