Release process

This page is for members of the palantir/blueprint team only.

1. Ensure the current changelog is up to date

Review the list of commits since the last "Publish" commit on develop.

Make sure that every meaningful change is documented in the changelog wiki page for the current major version (as of this writing, that's 5.x Changelog).

2. Create a release commit

Make sure you're on the latest develop commit.

git checkout develop
git pull

Use Lerna to bump version numbers and tag a release.

yarn lerna version

Lerna will interactively prompt you to select new version numbers. Review the changelog to determine what the new version for each package should be:

• if there are any new features in the specific package (including new icons), use a Minor release
• demo-app, docs-app, docs-data, and landing-app should be kept in sync with the core version
• otherwise, use a Patch release

lerna notice cli v6.5.1
lerna info versioning independent
lerna info Looking for changed packages since @blueprintjs/[email protected]
? Select a new version for @blueprintjs/core (currently 5.1.4) (Use arrow keys)
❯ Patch (5.1.5)
  Minor (5.2.0)
  Major (6.0.0)
  Prepatch (5.1.5-alpha.0)
  Preminor (5.2.0-alpha.0)
  Premajor (6.0.0-alpha.0)
  Custom Prerelease
  Custom Version

After this command exits successfully, it will have created a tagged release commit and pushed it to develop, which triggers a CI job to build & publish the libraries to NPM.

Note: this git push works because our current branch protection rules for develop do not include "require a pull request before merging". If/when this setting is updated, we will need to adopt an alternative release process (likely using Autorelease Bot).

Double-check that you pushed successfully by fast-forwarding to origin/develop (e.g. git pull --rebase origin).

3. Update documentation site

1. After a successful publish to NPM (can also check core package directly here, or follow the CI job on the "Publish" commit), run the following on develop to produce a clean build:

   yarn clean && yarn nx clear-cache && yarn compile && yarn dist

2. Run the docs preparation task to copy assets to the site/ directory and launch a local HTTP server:

   yarn site

3. Do a spot check on the local server to confirm that the site is in order and the version numbers you just released appear in the sidebar.

4. (If you haven't already) Create a second local check-out of the blueprint git repository at ../blueprint-gh-pages which is checked out at the gh-pages branch

5. Copy the locally-built docs site to your second git repo checkout:

   cp -r site/docs/ ../blueprint-gh-pages/docs/

6. Create a commit for the docs update:

   cd ../blueprint-gh-pages
   git add .
   git commit -m "docs v5.x" # replace this with the version of @blueprintjs/core just released

7. Push to the gh-pages branch:

   git push origin gh-pages

8. Update the changelog wiki page (e.g. 5.x Changelog) with the version numbers released. No need to document patch releases of packages with no significant changes.

Troubleshooting

If the release process fails mid-way, your local git repo may end up in a state that prevents it from re-attempting a release. When re-attempting the release, it'll try to create more git tags and another develop commit.

One way to fix is to delete all local git tags and re-fetch the tags that exist on GitHub.com

git tag -d $(git tag -l)
git fetch

If your local develop branch has additional commits that failed to push, we recommend ensuring develop matches origin/develop before rerunning yarn learn version.