# Releasing — TVU Design System

This document describes the release flow for `@nancyzeng0210/tvu-design-system` published to GitHub Packages.

> **Target audience**: maintainers releasing new versions.
> **External consumers**: see [`README.md`](../README.md) install section + the "External consumer setup" section below for `.npmrc` config.

---

## Pre-release checklist

Before releasing any version:

- [ ] On `master` branch, fully synced with `origin/master` (`git status` clean, `git log origin/master..HEAD` empty)
- [ ] All intended changes committed and pushed
- [ ] At least one `.changeset/*.md` file exists for the release (for 0.1.1+; not required for initial 0.1.0)
- [ ] Local typecheck passes: `pnpm exec vue-tsc --noEmit`
- [ ] Local build succeeds: `pnpm build`
- [ ] 10 strict audits pass locally (`prepublishOnly` will enforce this in CI too):
  ```bash
  pnpm run audit:icon-fill-currentcolor
  pnpm run audit:no-hardcoded-design-tokens
  pnpm run audit:component-no-inline-svg
  pnpm run audit:figma-conformance
  pnpm run audit:docs-site
  pnpm run audit:component-tokens
  pnpm run audit:tokenized-diff
  pnpm run audit:design-system
  pnpm run audit:published-vs-code
  pnpm run audit:translation-completeness
  ```

---

## Initial 0.1.0 release (one-time)

`v0.1.0` was created early as a placeholder pointing at a stale commit. Before first publish, move it to current `HEAD`:

```bash
# Delete stale local tag (it was never pushed to origin)
git tag -d v0.1.0

# Recreate at current HEAD
git tag v0.1.0

# Push tag — this triggers .github/workflows/publish.yml in CI
git push origin master --tags
```

CI will then run typecheck + build + 10 strict audits + `pnpm publish` to GitHub Packages.

Verify success at: `https://github.com/NancyZeng0210/TVU-Design-System/packages`

---

## Standard release flow (0.1.1+)

For every release after 0.1.0:

### Step 1 — Accumulate changesets (every meaningful PR)

```bash
pnpm changeset
```

The CLI will:
- Ask which bump type (`patch` / `minor` / `major`)
- Ask for a one-line summary
- Generate `.changeset/<random-name>.md` with your summary + version bump intent

Commit the generated file as part of your PR.

### Step 2 — Decide release time + run version bump

When ready to publish (e.g. you accumulated several changesets and want to ship them):

```bash
# View pending changesets
pnpm changeset:status

# Aggregate changesets → bump package.json version + update CHANGELOG.md
pnpm changeset:version
```

This will:
- Read all `.changeset/*.md` files
- Determine new version (max bump type wins)
- Update `package.json` `version` field
- Append a new section to `CHANGELOG.md` aggregating all changeset summaries
- Delete consumed `.changeset/*.md` files

### Step 3 — Commit + tag + push

```bash
git add -A
git commit -m "release v<NEW_VERSION>"
git tag v<NEW_VERSION>
git push origin master --tags
```

CI auto-publishes on tag push.

---

## Audit gate policy

| Audit | Gate | Behavior on failure |
|---|---|---|
| `audit:icon-fill-currentcolor` | **strict** | Blocks publish |
| `audit:no-hardcoded-design-tokens` | **strict** | Blocks publish |
| `audit:component-no-inline-svg` | **strict** | Blocks publish |
| `audit:figma-conformance` | **strict** | Blocks publish |
| `audit:docs-site` | **strict** | Blocks publish |
| `audit:component-tokens` | **strict** | Blocks publish |
| `audit:tokenized-diff` | **strict** | Blocks publish |
| `audit:design-system` | **strict** | Blocks publish |
| `audit:published-vs-code` | **strict** | Blocks publish (upgraded 2026-05-13 when BRIDGE-MOCKUP-004 tracker resolved — Chart + PopupBox both implemented in 0.1.3 / 0.2.0 lines) |
| `audit:translation-completeness` | **strict** | Blocks publish (added 2026-05-14 as Tier 1-A Sprint 4 gate over translation JSON schemas, aliases, verify hints, icons, and tokens) |

All 10 audits are strict gates in the `prepublishOnly` chain. Failures block `pnpm publish`. Previous warn-only `audit:published-vs-code` was upgraded 2026-05-13 after CANONICAL-010 (PopupBox, 0.1.3) + CANONICAL-011 (Chart, 0.2.0) both shipped — figma-only count is now 0. `audit:translation-completeness` was added 2026-05-14 after Tier 1-A split `translation/*` into JSON + schemas.

---

## External consumer setup

To install `@nancyzeng0210/tvu-design-system` from GitHub Packages, consumers need a GitHub Personal Access Token (PAT) with `read:packages` scope.

### Step 1 — Create PAT

`https://github.com/settings/tokens/new` → scope `read:packages` → generate.

### Step 2 — Configure `.npmrc`

In the consumer project root (or `~/.npmrc` for global):

```ini
@nancyzeng0210:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_PAT_HERE
```

> Do not commit `.npmrc` containing the token. Use environment variable interpolation if needed:
> ```ini
> //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_PAT}
> ```

### Step 3 — Install

```bash
pnpm add @nancyzeng0210/tvu-design-system
```

---

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `pnpm publish` exits with `ERR_PNPM_GIT_UNCLEAN` | Audit scripts wrote report files | CI workflow uses `--no-git-checks` to bypass; local publish: commit reports or use the same flag |
| CI `Publish` step fails with `401 Unauthorized` | Missing `permissions: packages: write` or wrong token | Check workflow `permissions:` block and `NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` env |
| CI workflow not triggered after tag push | Tag pattern mismatch (must be `vX.Y.Z`) | Use semver-compatible tag like `v0.1.0`, not `0.1.0` or `release-0.1.0` |
| `prepublishOnly` audit chain fails locally | One of 10 strict audits has FAIL output | Run the failing audit alone (`pnpm run audit:<name>`); fix code; retry |
| `audit:published-vs-code` fails (figma-only ≥ 1) | New Figma component published but code missing | Add canonical impl OR update `figma-data/figma-to-code-mapping.json` status |

---

## Reference

- Workflow file: [`.github/workflows/publish.yml`](../.github/workflows/publish.yml)
- changesets config: [`.changeset/config.json`](../.changeset/config.json)
- CHANGELOG: [`CHANGELOG.md`](../CHANGELOG.md)
- semver pre-1.0 rules: [https://semver.org/#spec-item-4](https://semver.org/#spec-item-4)