Skip to content

releasing

Jump to bottom
Kitty Hurley edited this page Feb 9, 2026 · 12 revisions

tags: [ci, release]

Releasing

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

Branches

Releases occur on special release branches, following 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.

Monthly releases

Before performing a scheduled release, check in with Franco and/or Kitty to confirm we are ready to release 🚀 and determine if there are any pull requests that need to be merged prior to starting the release process. 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

When running release we need to block PR merges to ensure new commits are not added to the code base or create merge conflicts when running release. 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 repo settings -> "Branches".

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

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

    image

Release steps

When it's 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 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 main 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, there should be a new PR with a cherry-pick 🍒 of the release commit to dev to update the package version and changelog section.
  • If the cherry-pick PR 🍒 was not created successfully, do this manually by cherry-picking the release commit from the release branch to dev and creating 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
  1. Review and merge the cherry-pick PR.
  2. Change the dev branch's required approvals back to 1 and save (see #prevent-merging-pull-requests).
  3. 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, then fix the CI after the release is completed. For example, if a generated file breaks the release due to an unclean working tree, build locally and submit a PR with the updated file. This avoids time pressure when determining a permanent fix. Reach out to Franco if a solution isn't clear.

  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 but true. To manually release next, run the following commands from the monorepo's root directory on the dev branch:

# make sure you don't have any unsaved work
git checkout dev
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), 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/[email protected]"
git tag -d "@esri/[email protected]"
git tag -a "@esri/[email protected]" -m "@esri/[email protected]" HEAD
git tag -a "@esri/[email protected]" -m "@esri/[email protected]" HEAD
# now you can publish and push tags

Patch releases

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

Best practices for limiting regressions and releasing patches when necessary:

Prior to release

  • When merging big items, author(s) 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.

Home

Tokens

Clone this wiki locally