uui-release-workflow

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

1. Merge all release changes to main branch
2. Update changelog.md with all released changes
3. Verify builds: yarn build
4. Provide pre-publish summary (version, packages, changelog highlights), ask user for permission, then run: yarn release
5. Follow console prompts
6. After successful release:
   • Publish changelog to GitHub Releases: https://github.com/epam/UUI/releases
   • Post in UUI Teams channel
7. 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 main
• changelog.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:

1. Revert latest commit (usually has version number in message)
2. Delete local tag: git tag -d <tag_name> (e.g., v5.7.0)
3. Delete remote tag: git push --delete origin <tag_name>
4. Try release again

Release Checklist

• All changes merged to main
• Changelog updated
• Builds verified (yarn build)
• GitHub and NPM accounts authenticated
• Pre-publish summary shown (version, packages, changelog)
• User permission obtained to publish to npm
• Run release command
• Publish changelog to GitHub Releases
• Notify team in Teams channel
• Sync main into develop (merge + PR if needed)
• Verify git log origin/develop..origin/main is empty