UI component library for Quantum Design System
This document describes how the automated release pipeline works for the Quantum Design System.
We use semantic-release to automate versioning and publishing based on Conventional Commits.
| 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 |
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
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 |
``
[optional body]
[optional footer(s)]
`
Examples:
`bashMinor release (new feature)
feat: add Tooltip component
prop from ButtonBREAKING 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 publishedManual 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/uiNote: 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 neededTroubleshooting
$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 troubleshootingConfiguration Files
| File | Purpose |
| ------------------------------- | ------------------------------ |
|
.releaserc.json | semantic-release configuration |
| .github/workflows/release.yml | GitHub Actions workflow |
| CHANGELOG.md` | Auto-generated changelog |