Skip to content

release-workflow.md

Latest commit

 

History

History
106 lines (90 loc) · 5.44 KB

release-workflow.md

File metadata and controls

106 lines (90 loc) · 5.44 KB
Raw

Release UUI packages workflow

Publishing to npm is done via GitHub Actions using npm Trusted Publishers (OIDC). No npm token or OTP is required — the CI workflow authenticates automatically.

One-time setup

See release-workflow-setup.md for initial configuration of Trusted Publishers and the npm-publish GitHub Environment.

Stable release

  1. Create a release branch from develop: release/vX.Y.Z
  2. Update changelog.md with mention of all released changes
  3. Ensure that all packages are building without errors — run yarn build
  4. Push the release branch to origin (Lerna pushes the version commit and tag to the remote branch): 
    git push -u origin release/vX.Y.Z
  5. Bump versions and create a git tag: 
    yarn release
    Lerna will prompt for version type (patch / minor / major). After confirmation, it commits the version bump, creates a tag vX.Y.Z, and pushes both to the release branch.
  6. Trigger the publish in GitHub Actions:
    • Go to Actions → Release → Run workflow
    • tag: the tag created in step 5 (e.g. v6.5.3)
    • dist_tag: latest
    • dry_run: false
    • Click Run workflow
  7. Approve the deployment in the npm-publish environment when prompted
  8. Monitor the workflow run — all 15 packages are published via npm publish --provenance in staged state (not yet visible to consumers)
  9. Promote each package on npmjs.com: open the package page → Versions → find the staged version → Promote to latest. Repeat for all 15 packages.
  10. After a successful release, publish the changelog to the GitHub Releases page (https://github.com/epam/UUI/releases) and in the UUI Teams channel (https://teams.microsoft.com/l/channel/19%3Af9ce97808e1e419cb976f71d310ca74f%40thread.skype/General?groupId=726eb5c9-1516-4c6a-be33-0838d9a33b02&tenantId=b41b72d0-4e9f-4c26-8a69-f949f367c91d)
  11. Open a PR from the release branch into main
  12. Sync main back into develop — do this right after the release, before new work lands on develop:
    1. Update local branches: git fetch origin
    2. Merge main into develop (use merge, not rebase): 
      git checkout develop
git pull origin develop
git merge origin/main
    3. Resolve conflicts if any:
      • package.json, lerna.json — take released versions from main
      • changelog.md — keep the released version section from main and add an empty unreleased # 6.x.x - xx.xx.2026 section on top (for the next changes on develop)
    4. Push via PR — develop is protected and requires an approving review: 
      git checkout -b sync/main-into-develop-vX.Y.Z
git push -u origin sync/main-into-develop-vX.Y.Z
    5. Verify sync: git log origin/develop..origin/main should be empty after the PR is merged.

Beta release

Same as stable release, with two differences:

  • In step 5, enter a prerelease version (e.g. 6.5.3-beta.0) when Lerna prompts
  • In step 6, set dist_tag to beta

When promoting (step 9), use the Promote to beta option instead of Promote to latest.

Legacy hotfix release (e.g. patch for v5.5.x while v6.x is current)

When the current latest is v6.x but a fix is needed for an older major version:

Warning — manual trigger only. The workflow fires automatically on every tag push with dist_tag: latest. For a hotfix on an old major version, that would silently overwrite the current v6.x as the default install. You must cancel the auto-triggered run and publish manually with dist_tag: hotfix instead (steps 5–6 below).

  1. Create a hotfix branch from the last tag of the target version: 
    git checkout -b hotfix/5.5.1 v5.5.0
  2. Cherry-pick release.yml from develop — it won't exist on old branches: 
    git checkout develop -- .github/workflows/release.yml
git add .github/workflows/release.yml
git commit -m "chore: add release workflow for hotfix branch"
  3. Apply the fix and commit
  4. Bump versions and create a tag: 
    yarn release
    When Lerna prompts, choose patch (or enter the exact version, e.g. 5.5.1). Lerna pushes the tag automatically — the auto-triggered workflow run will appear immediately.
  5. Cancel the auto-triggered run in GitHub Actions before it reaches the npm-publish approval gate.
  6. Trigger the publish manually:
    • Go to Actions → Release → Run workflow
    • tag: the hotfix tag (e.g. v5.5.1)
    • dist_tag: hotfix — never use latest, it would overwrite the current v6.x as the default install
    • Click Run workflow
  7. Approve the deployment in the npm-publish environment when prompted
  8. Promote each staged package on npmjs.com using the Promote to hotfix option. Repeat for all 15 packages.

After this, consumers can install the hotfix explicitly:

npm install @epam/uui@hotfix
# or by exact version:
npm install @epam/uui@5.5.1

No sync to main or develop is needed — hotfix branches are standalone.

Tips

  1. Revert failed release: if the release failed after Lerna created the version commit and tag but before packages were published:
    • Revert the latest commit with package version update
    • Delete local tag: git tag -d <tag_name> (e.g. v6.5.3)
    • Delete remote tag: git push --delete origin <tag_name>
    • Fix the issue and try again