npm package: @sendoutcards/quantum-design-ui
Description: UI component library for Quantum Design System
Author: nickqweaver
Latest version: 2.1.0

# Release Pipeline

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

## Overview

We use [semantic-release](https://semantic-release.gitbook.io/) to automate versioning and publishing based on [Conventional Commits](https://www.conventionalcommits.org/).

## 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:**

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

### Stable Version (Recommended)

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

### Canary/Prerelease Version

```bash
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](https://docs.npmjs.com/trusted-publishers).

#### 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](https://www.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](https://docs.npmjs.com/trusted-publishers#troubleshooting)

## Configuration Files

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