Releasing

Releasing

To release, you must have Admin privilege for the Calcite Design System repository.

major/minor/patch releases

When performing a scheduled release, first check in with Franco (or Matt if Franco isn't available) and Kitty 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).

Prevent merging pull requests

When releasing during normal work hours, you should block people from merging PRs while you're releasing. 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 main

4. Under "Require approvals" change the number from 1 to 6 and save the changes.

   

Release steps

The latest release process is mostly automated, but a few manual steps are required:

1. Review the PR created by release-please (titled "chore: release main") to make sure the changelog(s) and package versioning looks correct.

2. Add the skip visual snapshots label.

3. Make sure the rest of the PR checks are passing.

4. Approve and install the PR once all checks are passing. You will need to use Admin privilege to override the 6 approval rule added above.

5. Wait for the release's Deploy Latest action to finish.

6. Ensure the released package(s) were deployed to NPM and that GitHub Releases were created.

   • You can check the NPM version(s) on the website (e.g., calcite-components) or with the CLI:

     npm view @esri/calcite-components version

7. Reach out to Ben for investigation if something went wrong (this is unlikely now that everything is automated)

8. Change the main branch's required approvals back to 1 and save the changes (see the Prevent merging PRs section)

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 released by the CI after 'deployable' commits are installed to main. A deployable commit is:

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

If you need to disable next releases, you can do so by setting the NEXT_RELEASE_ENABLED GitHub Secret to anything but true. If you need to manually release next, you can run the following commands from the monorepo's root directory:

# make sure you don't have any unsaved work
git checkout main
npm run clean
npm install
npm test
npm run version:next
# verify the changelog and package versions look correct
npm run publish:next
npm run util:push-tags

IMPORTANT: If you need to change anything after running version:next (e.g., a changelog entry), make sure to amend the previous commit and recreate all of the tags using the new SHA (or HEAD) before continuing. For example:

# manual changelog entry updates were required after versioning...
git add packages/*/CHANGELOG.md
git commit amend --no-edit
git tag -d "@esri/calcite-components@1.2.3"
git tag -d "@esri/calcite-components-react@1.2.3"
git tag -a "@esri/calcite-components@1.2.3" -m "@esri/calcite-components@1.2.3" HEAD
git tag -a "@esri/calcite-components-react@1.2.3" -m "@esri/calcite-components-react@1.2.3" HEAD
# now you can publish and push tags

Maintenance releases for regressions and low risk PRs

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

Prior to release

• When installing big items, author(s) should:
  • Let either Kitty, Brittney, and/or Franco know of the proposed changes in advance so they can keep key stakeholders in the loop of the changes.
  • Post in the internal channel (Core - Releases 🔒) and public channel (Announcements and Releases) 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.

Scheduling

• The soonest a maintenance release can occur after a release should be coordinated with Kitty, Brittney, and Franco. A timeline and coordination helps to ensure stability, while also allowing enough time for users to find any other regressions so that we don't need to release multiple maintenance releases.
• Once we decide a maintenance release is needed, notify the public channel (Calcite Components) about the known issues and plans for an incoming maintenance release.
• 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.
  • After a maintenance release we should hold off on risky installs 24 hours to ensure stability if another maintenance release is necessary.
• 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 maintenance release to make sure everything is included.