Skip to content

releasing

Jump to bottom
Ben Elan edited this page Sep 27, 2024 · 6 revisions

tags: [ci, release]

Releasing

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

Monthly 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 dev

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

    image

Release steps

Active development occurs on the dev branch, and releases occur on main. When it is time to release, do the following:

  1. Follow the steps above to #prevent-merging-pull-requests.
  2. Make sure all of the workflows for the most recent commit on dev are completed, and next is deployed (if applicable).
  3. Run the "Deploy Latest" workflow following these steps or by running gh workflow run deploy-latest.yml. This will sync dev to main via rebasing.
  4. If the workflow fails, there was likely a merge conflict. This means you will need to run the commands and resolve the merge conflicts manually. The dev side of the merge conflicts should always be chosen. See the sync-dev-to-main step in deploy-latest.yml for the commands to run locally.
  5. Once the dev->main sync is complete, review the release-please pull request (titled chore: release main) to make sure the changelog(s) and package versioning looks correct.
    1. There should be a commit on the PR's branch named docs: remove prerelease changelog entries that occurred after the most recent commit on main.
  6. Make sure the rest of the PR checks are passing.
  7. Approve and install the PR once all checks are passing. You will need to use Admin privilege 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.

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

    npm view @esri/calcite-components version
  1. See the #troubleshooting section if something went wrong, or reach out to Ben or Franco for help.
  2. Cherry-pick the release commit (version bumps and changelog sections) from main to dev and create a PR. If there are merge conflicts, accept the main side. 
    git checkout -b ci/cherry-pick-release-commits origin/dev
git cherry-pick origin/main
gh pr create --fill
  3. Review and install the cherry-pick pull request.
  4. Change the dev branch's required approvals back to 1 and save the changes (see the #prevent-merging-pull-requests section)
  5. Let the team know via Teams merging is now unblocked in the initial Core - Releases message from earlier.

Troubleshooting

The following are some troubleshooting steps you can take if a release is unsuccessful.

  1. Find the workflow run for the release here, 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 then fix the CI after the release is completed. For example, if the components.d.ts file is outdated and breaks releases due to an unclean working tree, the temporary solution would be to build locally and submit a PR with the updated file. That way you won't be so time crunched when determining an actual fix to prevent the same error from occurring in the future. Reach out to Ben or Franco if a solution to the error isn't clear.

  3. Once the PR with the fix is installed, make sure the new workflow run is passing.

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

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

next releases

next releases are useful for testing incoming changes between releases. They are monorepo.md#ci-for-next-releases after 'deployable' commits are installed to dev. 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 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), 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/[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

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.

Home

Tokens

Clone this wiki locally