Releasing

---

tags: [ci, release]

⚠️ To release, you must have administrative privileges 🔐 for the Calcite Design System repository.

Branches

Releases occur on special release branches that follow the pattern releases/YY.R{1,3}, where:

• YY is the last two digits of the year
• R{1,3} is the release cycle for the year

For example, releases/26.R2 would be the branch for the second release in 2026.

Confirm Release

Before a scheduled release, check in with Franco and/or Kitty to confirm that we are ready to release 🚀 and to determine whether any pull requests need to be merged before the release process begins. Once they confirm readiness, follow the steps below. If you encounter errors or issues, refer to the troubleshooting section for help.

Prevent merging pull requests

During a release, block pull request merges to prevent new commits from being added to the codebase or creating merge conflicts. To prevent pull requests from merging (requires administrative privileges 🔐):

1. Notify Calcite team members via Teams in the Core - Releases 🔒 channel (use @Core - Releases for visibility 👀).

2. Go to the repository settings and select Branches.

3. Under "Branch protection rules," edit the entry for dev.

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

   

Reverting changes before a release

During final verification for a release milestone, a major issue or bug may be discovered in a change that is otherwise ready to ship. If the issue is likely to be obvious to users, do not leave the broken change in the release with the expectation that it will be fixed in a patch release. Coordinate with Franco and/or Kitty to decide whether the change must be reverted before release.

When a change is selected for a revert:

1. Communicate the decision in a team visible release discussion. Include links to the issue and revert pull request, explain what is being reverted and why, and identify any related work that should pause or be reverted (for example, corresponding Figma changes).
2. Create new comments on the issue with the revert decision and status updates of the revert and tag the PEs and Design for visibility.
3. Open a pull request to revert the change.
4. Update the description of the original pull request being reverted with a Release Please commit override so the original change is not included in the changelog. Add this block to the PR description, using a chore: commit message so it's not included in the changelog:

   BEGIN_COMMIT_OVERRIDE
   chore: <brief description of the reverted change>
   END_COMMIT_OVERRIDE
   

5. During release readiness checks, make sure to check for revert commits and trace each one to its original pull request. Confirm that the revert is included in the release branch and that the released code and changelog reflect the intended outcome.

Release steps

When it is time to release:

1. Follow the steps in #prevent-merging-pull-requests.
2. Ensure all workflows for the most recent commit on dev are complete and that next is deployed, if applicable.
3. Create a release branch from the latest dev, following the conventions in #branches.
4. Once the release branch is pushed, it will trigger the "Deploy Latest" workflow, which creates a release PR using release-please. This PR will be titled chore: release releases/YY.R{1,3} and tagged autorelease:pending.
   • If the PR isn't created within a few minutes, try to trigger the workflow manually by following these steps or by running gh workflow run deploy-latest.yml.
5. Review the release PR:
   • Ensure the changelog(s) and package versioning look correct.
   • Wait for a changelog-cleaning commit titled docs: remove prerelease changelog entries to be pushed after the most recent commit on the release branch. This is done by the remove-prerelease-changelog-entries.yml action, which runs automatically on changes to a release branch.
6. Make sure all PR checks pass.
7. Approve and merge the PR once all checks pass. You will need administrative privileges 🔐 to override the 6-approval rule.
8. Wait for the release's Deploy Latest action to finish.
9. Ensure the released package(s) were deployed to NPM and that GitHub Releases were created.
   • Note sometimes the NPM site is cached, you can confirm via an incognito browser.
   • You can check the NPM version(s) on the website (e.g., calcite-components) or with the CLI:

     npm view @esri/calcite-components version

10. Once the Deploy Latest workflow finishes, a new PR should be created to cherry-pick 🍒 the release commit to dev and update the package version and changelog section.

• If the cherry-pick PR 🍒 was not created successfully, cherry-pick the release commit from the release branch to dev manually and create a PR. If there are merge conflicts, accept the release-branch side.

  git checkout -b ci/cherry-pick-release-commits origin/dev
  git cherry-pick origin/<release-branch>
  gh pr create --fill

11. Review and merge the cherry-pick PR.
12. Change the dev branch's required approvals back to 1 and save (see #prevent-merging-pull-requests).
13. Notify the team via the initial Teams thread in the Core - Releases channel created earlier that merging is now unblocked.

Refer to the #troubleshooting section if something went wrong, or reach out to Franco for assistance and Kitty for coordination and communications.

Troubleshooting

If a release is unsuccessful, try the following steps:

1. Find the workflow run for the release in the deploy-latest.yml action, and view the logs to find the error message.

2. Fix the error. In some cases, you can resolve the issue with a temporary solution and fix the CI after the release is complete. For example, if a generated file prevents the release because it leaves the working tree unclean, build locally and submit a PR with the updated file. This avoids the time pressure of determining a permanent fix during the release. Reach out to Franco if the solution is unclear.

3. Once the PR with the fix is merged, make sure the new workflow run passes.

4. IMPORTANT: If the new release appears in GitHub releases but not on NPM, you'll need to release locally. This means the error involved publishing to NPM, which happens after releases and tags are created on GitHub. To release locally, run:

   npm install && npm run build && npm test && npm run publish:latest

If anything else comes up, please reach out to Franco for help.

next releases

next releases are useful for testing incoming changes between releases. They are released by the CI after 'deployable' commits are merged to dev. A deployable commit is:

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

To disable next releases, set the NEXT_RELEASE_ENABLED GitHub secret to anything other than true. To release next manually, run the following commands from the monorepo's root directory on the dev branch:

# Make sure you do not have any unsaved work.
git checkout dev
npm run clean
npm install
npm test
npm run version:next
# Verify that 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), amend the previous commit and recreate all 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.

Patch releases

For patch releases, fixes are merged into dev and then cherry-picked 🍒 onto the corresponding release branch for the patch. Once a fix is pushed to a release branch, it triggers the release workflow, which creates or updates a release PR for the patch. Otherwise, the steps are the same as for a normal release.

Best practices for limiting regressions and releasing patches when necessary:

Prior to release

• When merging large changes, authors should:
  • Notify Kitty and/or Franco of the proposed changes in advance so they can keep key stakeholders in the loop.
  • Post in the internal channel (Core - Releases 🔒) and public channel (Announcements and Releases) to watch 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 patch release can occur after a release should be coordinated with Kitty and Franco. A timeline and coordination help ensure stability, while allowing time for users to find other regressions so multiple patch releases aren't needed.
• Once a patch release is needed, notify the public channel (Calcite Components) about the known issues and plans for an incoming patch release.
• 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 release to make sure everything is included.