| name | uui-release-workflow |
| description | Guides the UUI package release process including stable and beta releases, changelog updates, and handling failed releases. Use when releasing UUI packages, updating changelog, or troubleshooting release issues. For maintainers only. |
UUI Release Workflow
Important
Always ask for explicit user permission before running yarn release or yarn release-beta. These commands publish packages to npm and cannot be undone. Never publish to npm without confirming the user intends to do so.
Before asking for permission, provide a pre-publish summary:
- Version: The version that will be published (from
changelog.md top section or Lerna)
- Packages: Which packages will be published (from
package.json workspaces)
- Summary: Brief highlights of changes from the current
changelog.md entry
Then ask the user to confirm before running the release command.
Prerequisites
- Terminal logged into UUI GitHub account
- NPM account with write access to UUI packages
- For MFA: Generate Access Token in NPM profile
Stable Release
- Merge all release changes to
main branch
- Update
changelog.md with all released changes
- Verify builds:
yarn build
- Provide pre-publish summary (version, packages, changelog highlights), ask user for permission, then run:
yarn release
- Follow console prompts
- After successful release:
- Sync
main back into develop (required after every stable and beta release)
Sync main into develop
Do this immediately after a successful release, before new commits land on develop.
yarn release / yarn release-beta create version-bump commits only on main. Without syncing back, develop keeps old package versions and the branches diverge.
Steps
git fetch origin
git checkout develop
git pull origin develop
git merge origin/main
Resolve conflicts if any:
package.json, lerna.json — take released versions from mainchangelog.md — keep the released version section from main; add an empty unreleased # 6.x.x - xx.xx.2026 section on top
develop is protected — push via a sync branch and open a PR:
git commit -m "Merge branch 'main' into develop after vX.Y.Z release"
git checkout -b sync/main-into-develop-vX.Y.Z
git push -u origin sync/main-into-develop-vX.Y.Z
After the PR is merged, verify:
git fetch origin
git log origin/develop..origin/main
Output must be empty.
Rules: use merge, not rebase. Do not squash the sync PR — preserve release history.
Beta Release
Provide pre-publish summary, then ask user for permission before running. Use beta dist-tag instead of latest:
yarn release-beta
NPM Login with MFA
If using MFA, login with access token:
npm config set //registry.npmjs.org/:_authToken=your_token
Handling Failed Releases
If release fails and packages aren't published, revert Lerna commits and tags:
- Revert latest commit (usually has version number in message)
- Delete local tag:
git tag -d <tag_name> (e.g., v5.7.0)
- Delete remote tag:
git push --delete origin <tag_name>
- Try release again
Release Checklist
