Releasing

beta releases

beta releases are currently scheduled for once a month (two sprints per release). If necessary, beta releases can happen more often for patches.

First time setup

Setting up an access token for release

In order for the release script to work, you'll need to generate an access token (repo scope) with GitHub and export it into your shell environment as GH_RELEASE_GITHUB_API_TOKEN. First, generate a token, then copy that token and add it to your bash_profile (~/.bash_profile on Mac):

export GH_RELEASE_GITHUB_API_TOKEN=PASTE_TOKEN_HERE

You may need to start a new terminal window to apply the profile changes.

npm Setup

Setup your npm locally by running npm login. Have your username, password, and 2FA app handy. You will only need to set this up once on your machine.

Release process

Prevent merging PRs

When releasing during normal work hours, you should block people from merging PRs while you're releasing. If a PR is merged mid-release you will need to start over. To "block" PRs do the following (requires admin privilege):

1. Let the team know via Teams in the Core - Releases 🔒 channel (@ the channel for visibility)
2. Go to the repo settings -> "Branches"
3. Under "Branch protection rules" edit the entry for master
4. Under "Require approvals" change the number from 1 to 6

5. Release (steps below)
6. Change the required approvals back to 1

Release

To release a new version of Calcite Components you must:

Note: make sure not to release from a fresh clone, see issue #4246

1. Be a member of the @esri organization on npm.

2. Be a member of the admin team for Calcite Components.

3. Make sure you have a remote named origin pointing to Esri/calcite-components.

4. Ensure you have set up an access token. Alternatively, you can skip adding an access token and manually release to GitHub following steps 7-9 below.

5. Run npm run release:prepare. This script will:

   • Create a build
   • Run all the tests
   • Update the package version
   • Create a changelog entry for the current release
   • Create a commit and tag it - ⚠️ Note if you need to make changes after this step, make sure to amend the commit (git commit --amend) and recreate the tag (git tag --force <version>)

6. Run npm run release:publish. This script will:

   • Push the release tag to the repo
   • Publish to NPM
   • Publish to GitHub (including source and package)

That's it if everything goes well. Make sure to change the required approvals back to 1 and let the team know via Teams. There are a couple extra steps if you didn't set up a PAT as described above:

7. The last part of the publish script will fail with an auth error. Go to the GitHub website and create a new release using the new tag. Make the release name the same as the tag. Copy and paste the changelog for the release into the notes.

8. Download the binaries from npm, e.g. for beta.X go to:

   • https://registry.npmjs.org/@esri/calcite-components/-/calcite-components-1.0.0-beta.X.tgz

9. Attach the binaries to the GitHub release and press "Publish release".

Storybook

We deploy the docs with storybook deployer. A GitHub Action does this automatically once a week. You can optionally build and deploy storybook manually by running npm run release:docs. This script will:

• Create the component doc
• Create the storybook build
• Push all doc content to the gh-pages branch

Note: this script can be run anytime the docs need to be updated

Output targets and JSAPI CDN

See this internal doc to release the output targets and deploy to the CDN.

Bumping the examples

A GitHub Action will automatically bump the versions in calcite-components-examples and open a PR on Wednesday night after the release. While in beta, review/accept the PRs and test them locally every once in a while. Here is the script if any changes are needed.

next releases

next releases are useful for testing incoming changes between releases. They are deployed by the CI and happen if changes between tagged releases (beta or next) have 'deployable' commits. A deployable commit is:

1. a commit of type feat or fix
2. a commit type that introduces a breaking change

Release process

In order to enable next releases, the NEXT_RELEASE_ENABLED GitHub Action secret needs to be true. This variable enables the deploy action to run after each successful build. When enabled, each deploy phase will run a script that runs to determine whether there are deployable commits after the last release. If this is the case, a calcite-components production build will be created, tagged and committed then pushed to the repository and then deployed to NPM.

Release patches and regressions

The following are best practices for limiting regressions and releasing patches when necessary.

Prior to release

• When installing big items, author(s) should post in the internal channel (Core - Releases 🔒) and public channel (Calcite Components) to keep an eye out for issues related to the changes. This should happen after the item's PR is merged and next is deployed so users can start testing early.

Patching

• The soonest a patch can occur after a release is one week. This is to allow enough time for users to find any other regressions so that we don't need to release multiple patches.
• Once we decide a patch is needed, notify the public channel (Calcite Components) about the known issues and plans for an incoming patch.
• Inform the team in the internal release channel to hold off on risky installs, revert any that landed, and to (re)install after the patch.
• Check-in daily with the team in the internal release channel about known issues, reported regressions, and fix statuses.
• Remind the team two days before and the day of the scheduled patch to make sure everything is included.