Release Pipeline

This document describes how the automated release pipeline works for the Quantum Design System.

Overview

We use semantic-release to automate versioning and publishing based on Conventional Commits.

Branch Strategy

| Branch | Purpose | npm Tag | Example Version | | -------- | ----------------------- | -------- | ---------------- | | master | Stable releases | latest | 2.0.0, 2.1.0 | | canary | Prerelease/alpha builds | canary | 2.1.0-canary.1 |

How It Works

Automatic Releases

When code is merged to master or canary, the CI pipeline:

1. Checks out the code
2. Installs dependencies
3. Runs linting (npm run lint)
4. Builds the library (npm run build)
5. Analyzes commits since the last release
6. Determines the version bump based on commit types
7. Updates package.json and CHANGELOG.md
8. Creates a git tag
9. Publishes to npm
10. Creates a GitHub Release with release notes

Version Bumps

The version bump is determined by commit message prefixes:

| Commit Type | Description | Version Bump | Example | | ------------------------------ | ----------------------- | ------------- | -------------------------------- | | feat: | New feature | Minor (0.1.0) | feat: add new Button variant | | fix: | Bug fix | Patch (0.0.1) | fix: correct padding on Card | | perf: | Performance improvement | Patch (0.0.1) | perf: optimize re-renders | | refactor: | Code refactoring | Patch (0.0.1) | refactor: simplify Div logic | | feat!: or BREAKING CHANGE: | Breaking change | Major (1.0.0) | feat!: remove deprecated props | | docs: | Documentation only | No release | docs: update README | | style: | Code style changes | Patch (0.0.1) | style: fix formatting | | chore: | Maintenance tasks | Patch (0.0.1) | chore: update dependencies | | test: | Test changes | No release | test: add unit tests | | ci: | CI changes | No release | ci: update workflow |

Commit Message Format

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

Examples:

# Minor release (new feature)
feat: add Tooltip component

# Patch release (bug fix)
fix: correct z-index on Modal overlay

# Major release (breaking change)
feat!: remove deprecated `size` prop from Button

BREAKING CHANGE: The `size` prop has been removed. Use `variant` instead.

# No release (documentation)
docs: update component examples

Installing Packages

Stable Version (Recommended)

npm install @sendoutcards/quantum-design-ui

Canary/Prerelease Version

npm install @sendoutcards/quantum-design-ui@canary

Workflow

Normal Development

1. Create a feature branch from canary
2. Make changes with conventional commit messages
3. Open a PR to canary
4. On merge, a canary release is automatically published

Stable Release

1. Open a PR from canary to master
2. On merge, a stable release is automatically published

Hotfix

1. Create a branch from master
2. Make the fix with conventional commit messages
3. Open a PR directly to master
4. On merge, a patch release is automatically published

Manual Version Override

If you need to force a specific version (rare):

1. Manually update the version in packages/ui/package.json
2. Commit with message: chore(release): 2.0.0 [skip ci]
3. Push to the appropriate branch
4. Manually run npm publish from packages/ui

Note: This bypasses the automated changelog generation.

Setup Requirements

npm Authentication (Trusted Publishing)

This repository uses npm Trusted Publishing via OpenID Connect (OIDC) for secure, token-free publishing. This eliminates the need for long-lived npm tokens that require manual rotation.

For more information, see the npm Trusted Publishing documentation.

How It Works

1. The GitHub Actions workflow requests an OIDC token from GitHub
2. npm verifies the token came from our authorized repository and workflow
3. npm allows the publish without any stored secrets

GitHub Secrets

| Secret | Description | | -------------- | ---------------------------------------- | | GITHUB_TOKEN | Automatically provided by GitHub Actions |

Note: No NPM_TOKEN is required. Authentication is handled automatically via OIDC.

Trusted Publisher Configuration (npmjs.com)

The trusted publisher is configured on npmjs.com with these settings:

| Field | Value | | ----------------- | ----------------------- | | Organization | SendOutCards | | Repository | quantum-design-system | | Workflow filename | release.yml | | Environment | (none) |

To modify the trusted publisher configuration:

1. Go to npmjs.com and log in
2. Navigate to the package settings for @sendoutcards/quantum-design-ui
3. Find the "Trusted Publisher" section
4. Update the GitHub Actions configuration as needed

Troubleshooting

Release didn't trigger

• Ensure commits follow conventional commit format
• Check that the branch is master or canary
• Verify the CI workflow completed successfully

Version wasn't bumped

• Commits like docs:, test:, ci: don't trigger releases
• Commits with style: or chore: now trigger patch releases

npm publish failed

• Verify the trusted publisher is configured correctly on npmjs.com
• Ensure the workflow filename matches exactly (release.yml)
• Check that id-token: write permission is set in the workflow
• Ensure the package name is available on npm
• See npm Trusted Publishing troubleshooting

Configuration Files

| File | Purpose | | ------------------------------- | ------------------------------ | | .releaserc.json | semantic-release configuration | | .github/workflows/release.yml | GitHub Actions workflow | | CHANGELOG.md | Auto-generated changelog |