Releasing

major/minor/patch releases

First time setup

Before releasing, you will need to create an NPM account and login on the command line. 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. You will also need ask Jeremy or Franco to be given permission to publish to the Esri NPM Organization packages.

In order for the release to be fully automated, 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. Alternatively, there are manual steps below for publishing the GitHub release if you aren't comfortable saving a GitHub token in plaintext.

Release process

When performing a scheduled release, first check in with Franco (or Matt if Franco isn't available) and Ben to see if there are any pull requests that need to be merged before releasing. Once they say we are ready for release, follow the steps below. If you run into errors or other issues during the release steps, you can reach out to Ben for help (or Franco if Ben isn't available). If the release issues aren't resolved until the following day, you can release without asking for approval again. Franco or Ben will reach out if the release needs to be delayed until additional pull request(s) are merged.

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:

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. Added your GitHub PAT to a local enivorment variable. 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)

   You can verify the npm version with npm view @esri/calcite-components version. If it's on the current release - 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, (change it to the correct version):

   • https://registry.npmjs.org/@esri/calcite-components/-/calcite-components-1.0.9.tgz

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

Output targets, JSAPI CDN, and Developer documentation

See this internal doc to release the output targets, deploy to the CDN, and bump the calcite versions in the Developer documentation.

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. Make sure to test the samples when there are major changes. 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 releases have 'deployable' commits. A deployable commit is:

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

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.