Skip to content

Latest commit

 

History

History
569 lines (439 loc) · 24.6 KB

release.md

File metadata and controls

569 lines (439 loc) · 24.6 KB
Raw

Release

How we version and release packages in the Design System

Table of Contents

Overview

The Design System follows a time-based release model where we deliver a stable minor update every two weeks. The full schedule for releases is available here.

We also publish prereleases before every minor release. This prerelease happens several days before the stable release. This offers an integration window where the prerelease can be tested on products before the stable release.

We also ship security and bug fixes in patch releases. This will be shipped as-needed and do not follow a specific schedule.

Release Team

The release team is responsible for coordinating the minor and patch releases for the Design System in a given week. This group is composed of a release lead and sidekick. The release lead is responsible for:

  • Managing the release itself, including
    • Testing
    • Publishing
    • Support
  • Helping the release sidekick understand and run through the release process, where appropriate

The release sidekick is responsible for:

  • Learning how to run the release process if this is your first time on the release team
  • Helping out the release lead in the release process, this includes helping with testing, publishing, support, and more

Process

When going through a release, the release team will go through the following checkpoints:

Checkpoint Description
Prerelease Publish a prerelease that will be used to test out the release candidate before becoming stabilized
Stable release Graduate the prerelease into a stable release that is available through packages on NPM
Post release Support the latest stable release and address any issues that may come up as a result of promoting the release to stable
Previous release Determine if new changes to v10 are present and need published, and do so if needed.

Prerelease

The prerelease occurs on the last Monday of a sprint. During this stage, the release team will need to do the following:

  • Run the Version Workflow to automatically generate the prerelease versions for packages

Screenshot of the version workflow with a way to manually trigger the action

  • Specify preminor as the release type
  • Provide the tag for the release. For example, if the previous release was v11.1.0 this tag would be v11.2.0-rc.0. To find the previous release, view the tag list.
  • Review and approve the Pull Request generated from this action
  • 🛑 Wait for the Pull Request to be merged
  • Once merged, pull down the latest code from upstream
git checkout main
git pull upstream main
  • Run git log to view the most recent commits
  • Validate the most recent commit is the release commit from the PR. If it is not, ensure the PR has been merged and try pulling again.
chore(release): v11.2.0-rc.0
  • Exit the log by pressing q
  • Tag the release commit, and push it to upstream
git tag -a v11.2.0-rc.0 -m 'v11.2.0-rc.0'
git push upstream v11.2.0-rc.0

Releasing another prerelease

After a prerelease has been published, additional prereleases can be published. eg. v11.12.0-rc.0 -> v11.12.0-rc.1

To do so, follow the above steps for Prerelease but specify prerelease as the release type instead of preminor.

Stable release

A stable release occurs on the last Wednesday and finishes later in the day. This should occur after the prerelease has been tested and validated. During this stage, the release team will do the following:

  • Run the Version Workflow to automatically generate the prerelease versions for packages
    • Specify minor as the release type
    • Provide the tag for the release. For example, if the previous release was v11.1.0-rc.0 this tag would be v11.1.0. To find the previous release, view the tag list.
  • Review and approve the Pull Request generated from this action
  • 🛑 Wait for the Pull Request to be merged
  • Once merged, pull down the latest code from upstream
git checkout main
git pull upstream main
  • Run git log to view the most recent commits
  • Validate the most recent commit is the release commit from the PR. If it is not, ensure the PR has been merged and try pulling again.
chore(release): v11.10.0
  • Exit the log by pressing q
  • Tag the release commit, and push it to upstream
git tag -a v11.2.0 -m 'v11.2.0'
git push upstream v11.2.0

The packages that have been published will be switched to latest on the last Wednesday of a sprint. To make the switch, you will need to:

  • Run the Promotion Workflow to automatically promote Carbon packages with new release versions to latest
  • Verify the packages have been promoted to latest on NPM
  • Update the latest release notes with the generated output from Carbon Cli by running at /carbon

./packages/cli/bin/carbon-cli.js changelog v11.5.0..v11.6.0

  • Uncheck "this is a prerelease" on the Release

  • Post the release announcement in slack

    • #carbon-announcements
    • #carbon-design-system
    • #carbon-react
Click to view slack announcement template 
:carbon10: :carbon10: :carbon10:

Hi all! :wave: We wanted to share the release notes for [v11.X.Y](https://github.com/carbon-design-system/carbon/releases/tag/v11.X.Y) 🚀

This release includes the following updates that you and your team can use today:

* item
* item
* item
* ... and a number of additional bugs squashed! 🐛

If you want to stay up to date with our release schedule, check out our [Release Radar wiki page](https://github.com/carbon-design-system/carbon/wiki/Release-radar).

If there are any issues that come up while using this release, please reach out on GitHub or Slack to let us know!

Thanks :tada:
— The Carbon team :carbon10:

Or, use the Slack Block Kit Builder announcement template

Update gatsby-theme-carbon and carbon-website

After the promotion workflow is completed this will trigger the deploy-packages workflow to update both design-language-website and gatsby-theme-carbon to the latest version of the Carbon packages.

  • Review, approve and merge the Pull Request generated from this action in gatsby-theme-carbon to verify no breaking changes have occurred in this release. If the PR from the previous release was not merged, the existing PR will be updated. This should trigger an automatic release of gatsby-theme-carbon.
  • Check that gatsby-theme-carbon has been released and is on the latest version of Carbon
  • Run the Update Carbon and gatsby-theme-carbon deps workflow to automatically open a PR in the Carbon website to update to latest Carbon and gatsby-theme-carbon versions.
  • Review and approve the pull request generate by the workflow.

Post release

After a release has switched packages from next to latest, it is important to monitor channels on Slack and issues on GitHub in case breaking changes may have occurred in the release.

If issues occur for the specific release, it's important to determine the next best steps based on the type of issue. Typically, issues fall into one of two categories:

  • Hotfix: if the issue is self contained and can be addressed quickly, going through a patch release may be the easiest way to resolve the issue
  • Revert to previous stable release: this strategy is helpful if the issue that has been identified is not able to be quickly remediated or the timeline is unknown

Manual Patch Release

Occassionaly we need to do an off-cycle patch release to fix some broken functionality that was inadvertedly published in a previous release. In such cases, follow these steps below to ensure a proper patch release:

  • Go to your local version of the monorepo

  • Ensure your monorepo is up to date: git fetch upstream

  • Checkout to the tag of the release you want to publish a patch for (most likely the latest release tag, to find the previous release, view the tag list). git checkout release/vX.Y.Z

  • Create a new release branch with the intended version to be released. Should be the same release that we previously checked out to incremented by +0.0.1 to account for a new patch version.

    • git checkout -b release/vX.Y.Z

  • Cherry pick the commit(s) that you want added onto the patch release (these should be the hotfixes): git cherry-pick ######

  • Run git log to view the most recent commits

  • Validate the most recent commits are the release commit from the tag you pulled in followed by the commit(s) you cherry-picked in.

  • Exit the log by pressing q

  • Run the following lerna command to version packages that have changed since the last version

    yarn lerna version patch --no-git-tag-version --no-push --yes

  • Verify in your changed files that all affected package versions have changed by +0.0.1 (a patch version)

  • Run yarn install

  • Confirm that all file changes are either package.json files or the yarn.lock, no other files should have changes at this point.

  • Commit the changes by running:

    git add -A
git commit -m 'chore(release): vX.Y.Z'
git push --set-upstream origin release/vX.Y.Z

  • Make a Pull Request with your branch

    • Set the base branch of the PR to be main
    • Title of PR: chore(release): vX.Y.Z
    • Description: Release PR for vX.Y.Z, includes hotfixes from commit(s) ######

  • Close the PR (we just opened it to have the release tracked in the github history). When closing, add a comment stating that this was a manual release and that the PR doesn’t need to be merged

  • Tag the release commit, and push it to upstream

    • Make sure you're setting the correct tag version number.

      git tag -a vX.Y.Z -m 'vX.Y.Z'
git push upstream vX.Y.Z

  • Verify that your push triggered a release action

  • Verify that the action succeeded and the Release was published under the next tag on NPM

  • If the released package version looks correct, you'll need to manually promote the necessary Carbon packages with new release versions to latest.

    Note:

    • Do NOT do this for the carbon-components package.
    • You need to use the individual generatied version number for the package here, not the released github tag version.

  • for each package (replace carbon-components-react with the package name):

    npm dist-tag add [email protected] latest

  • Verify the packages have been promoted to latest on NPM

  • Update the latest release notes with the generated output from Carbon Cli by running from the root of the monorepo

    ./packages/cli/bin/carbon-cli.js changelog vA.B.C..vX.Y.Z

Previous releases (v10)

From the initial v11 release in March 2022 until September 30, 2024 we supported the previous major version of the Design System (v10). During this time v10 only received bug fixes when requested, and critical security updates. All v10 code and assets reached end of support on September 30, 2024.

The content below relating to the v10 release process is only kept here for posterity and should be removed from this document in the next major release.

How to determine if the previous major version needs to be released

To help determine if there has been code merged into the v10 branch since the last v10 release:

  • Go to https://github.com/carbon-design-system/carbon/compare/
  • Open the "base" ref dropdown
  • Choose the "tags" tab
  • Select the most recent v10.x tag
  • Open the "compare" ref dropdown
  • Select the v10 branch
  • View the diff
    • If the diff is empty, v10 does not need released
    • If the diff contains a list of commits, we need to release a new v10.x version

Additionally, check the PR queue against the v10 base branch. It might be that there is a PR open and waiting to merge that we could get in to include in the release.

Releasing the previous major version

  • Go to your local version of the monorepo
  • Checkout v10 git checkout v10
  • Run git pull upstream v10 --tags
  • Create a new release branch from main with the intended version to be released. To find the previous release, view the tag list.
    • git checkout -b release/vX.Y.Z
  • Run yarn install
  • Ensure your working directory is clean via git status,
  • Run the following lerna command to version packages that have changed since the last version
yarn lerna version patch \
  --no-push \
  --no-git-tag-version
  • Double-check the version bumps to make sure they match what you're expecting. As a patch, they should:
    • NOT include a breaking change (e.g. it should not be v10.14.0 → v11.0.0)
    • NOT include a minor change (e.g. it should not be v10.59.1 -> v10.60.0)
  • Hit y to confirm changes
  • For a quick sound check, run yarn install --immutable --immutable-cache to make sure all the versions have been correctly bumped
    • Note: sometimes you will need to update the root package.json file manually
  • Run yarn install
  • Commit the changes to the package.json files by running:
git add -A
git commit -m 'chore(release): vX.Y.Z'
git push --set-upstream origin release/vX.Y.Z
  • Make a Pull Request with your branch
    • Set the base branch of the PR to be v10
    • Title of PR: chore(release): vX.Y.Z
    • Description: Release PR for vX.Y.Z
  • 🛑 Wait for the Pull Request to be merged
  • Once merged, pull down the latest code from upstream
git checkout v10
git pull upstream v10
  • Run git log to view the most recent commits
  • Validate the most recent commit is the release commit from the PR. If it is not, ensure the PR has been merged and try pulling again.
chore(release): v10.59.1
  • Exit the log by pressing q
  • Tag the release commit, and push it to upstream
    • Make sure you're setting the correct tag version number. To find the previous release, view the tag list.
git tag -a vX.Y.Z -m 'vX.Y.Z'
git push upstream vX.Y.Z
./packages/cli/bin/carbon-cli.js changelog vA.B.C..vX.Y.Z

Releasing a new major for a single package

In some cases, a single package in the monorepo may need a major version bump. This can be done without having to do a major version bump across all packages.

For instance:

  • eslint-config-carbon needs a new major
  • All other packages should only be bumped as a new patch
  • The tag for the release should remain at the curent major v11.x, and not be bumped to v12.x

To do this, packages must be versioned manually.

  1. Switch to main
  2. Pull in latest git pull upstream main
  3. Make a new branch with the version you're going to release, e.g. git checkout -b release/v11.23.1
  4. Run yarn lerna version --no-git-tag-version --no-push
  5. An interactive prompt will be presented - select the appropriate version bump for each package
  6. After the interactive prompt is complete, run yarn install to update yarn.lock
  7. Commit chore(release): v11.23.1
  8. git push and then open a pull request
  9. Once the changes are merged in, follow the same steps for a Stable Release after the 🛑 Wait for the Pull Request to be merged step to tag the release commit and trigger the automated release workflows.

Troubleshooting

The Version workflow succeeded, but the PR was not created

Look through the logs - Lerna probably didn't detect any changes that need published. This can happen if there is nothing new in main since the most recent tag was published. Merging a PR and running the workflow again (don't re-run the previous one) should fix this.

Something failed in the Version workflow

If the Version workflow fails for some reason and you can't determine the cause, you can always run the same commands from the workflow file in your local dev environment as long as you have push access to the repo.

  1. On a clean working directory, pull down the latest from main and create a release/vX.Y.Z branch:
git checkout main
git pull upstream main
git checkout -b `release/vX.Y.Z`
yarn install
yarn build

  1. Then run the rest of the commands specified in the Version.yml workflow. yarn build, yarn lerna ..., yarn install, etc.

  2. Commit and push up the changes to a PR and you're at the same step in the process as if the Version workflow had succeeded.

git add .
git commit -m "chore(release): vX.Y.Z"
git push

Something failed in the Release workflow

If the Version workflow fails for some reason and you can't determine the cause, you can always run the same commands from the workflow file in your local dev environment as long as you have push access to the repo and publishing access in npm.

  1. Pull down the tag locally:
git checkout vX.Y.X

  1. Run the same commands in order from the Release.yml workflow.

  2. On success, manually create a GitHub release associated with the proper tag, and include the generated changelog.

We're getting reports of unpkg links not working

Reports like these can be the result of unpkg's default behavior of resolving https://unpkg.com/carbon-components/* to the version corresponding to the latest tag.

It's likely that the latest tag was erroneously applied to a v11.x version, causing anyone using a non-versioned unpkg link to begin resolving to the v11 package which does not contain a compiled stylesheet.

To fix, re-apply the latest tag to v10.x instead of v11.x. Any non-versioned unpkg links should now resolve to [email protected] again.

npm dist-tag add [email protected] latest

Instruct users to prevent this in the future by appending @10 to the package name to ensure unpkg resolves to the latest v10 version:

https://unpkg.com/carbon-components@10/css/carbon-components.min.css https://unpkg.com/carbon-components@10/scripts/carbon-components.min.js

When running the v10 storybook deploy manually, the v11 storybook is being published to v7-react.carbondesignsystem.com

The workflow needs to be ran from the v10 branch. Select v10 from the dropdown when you run it.

image