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

$3

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

$3

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 |

$3

``
():

[optional body]

[optional footer(s)]
`

Examples:

`bash


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

$3

`bash
npm install @sendoutcards/quantum-design-ui
`

$3

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

Workflow

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

- 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 |