# Next Session Pickup — v0.2.0 Publish

> **用途**：新 session 起手直接读本文件，按 §2 步骤发 v0.2.0。
> **前任**：[`next-session-pickup-2026-05-13-f20.md`](next-session-pickup-2026-05-13-f20.md) → F20/F21 v1/F26/F29/CANONICAL-011 全 done
> **目标版本**：v0.1.3 → **v0.2.0**（minor，触发 = `Chart` 新 canonical export）

---

## TL;DR

1. CANONICAL-011 Chart 实现 + audit gate upgrade 全 done in 2026-05-13 session 9。**v0.2.0 所有 src/ 改动已 commit + push** 到 master。
2. **唯一剩余**：写 changeset + version bump + tag push + CI 跑 + Packages 页 **必须** verify 实物。
3. **预计 ~15-20min** 完成发布全流程。

---

## 1. 当前状态确认（起手必做）

```bash
git status                                  # 应 0 dirty 或仅 docs/figma-data unrelated dirty
git log --oneline -10                       # 最新 commit 应是 wrap-up commit
pnpm test                                   # 应 105 passed | 1 skipped
pnpm build                                  # 应 ✅
pnpm audit:published-vs-code               # 应 38 matched / 0 figma-only
```

如 4 项任一不绿，**不要**继续 publish — 先排查。

---

## 2. v0.2.0 Publish 步骤

### Step 1 — 写 changeset（~2min）

```bash
pnpm changeset
```

选择：
- Bump type: **minor**（CANONICAL-011 是新 export，不是 patch）
- Summary（一句话，会进 CHANGELOG）：

  ```
  CANONICAL-011: Chart canonical component (6 variants pie/donut/line/bar/bar-horizontal/line-bar)
  powered by Chart.js + vue-chartjs (peerDeps); 12-color chart palette
  (--chart-color-1..12) following TVU HSL hue-rotation rule; canonical wrapper
  with defineAsyncComponent lazy load (zero bundle cost for non-chart pages);
  CSS-var-driven theme switching via MutationObserver. BRIDGE-MOCKUP-004 tracker
  closed (audit:published-vs-code upgraded to 9th strict gate).
  ```

Commit 生成的 `.changeset/<name>.md` 进单独 commit。

### Step 2 — Version bump + CHANGELOG 聚合（~1min）

```bash
pnpm changeset:version
```

会自动：
- 把 `package.json` `"version": "0.1.3"` → `"0.2.0"`
- 把 `.changeset/<name>.md` 内容聚合进 `CHANGELOG.md` 顶部
- 删 `.changeset/<name>.md`

**verify**：
- `cat package.json | grep version` → `"version": "0.2.0"`
- `head -20 CHANGELOG.md` → 顶部应是 `## 0.2.0` 段

### Step 3 — Commit version bump（~1min）

```bash
git add package.json CHANGELOG.md .changeset/
git commit -m "release: v0.2.0"
git push
```

F21 hook 会跑（typecheck + vitest + figma-data 检测 + visual approval check）。Visual check 触发吗？changeset commit 不含 .vue/.css 应该不触发。如触发用 `VISUAL_COMMIT_APPROVED=1`。

### Step 4 — Tag + 触发 CI（~30s）

```bash
git tag v0.2.0
git push origin v0.2.0
```

⚠️ Tag 必须 `vX.Y.Z` 格式（不是 `0.2.0` 或 `release-0.2.0`），否则 CI workflow 不触发。

### Step 5 — 监控 CI（~3-5min）

打开 https://github.com/NancyZeng0210/TVU-Design-System/actions

预期看到「Publish」workflow run。等它跑完。

CI 跑：
- typecheck + build（via `prepare` script）
- prepublishOnly = **9 strict audits**（含本次升 strict 的 audit:published-vs-code）
- pnpm publish 到 GitHub Packages

如某个 audit 失败 → run fail → 不会 publish。诊断步骤：
- 看 Actions 页 workflow run 找 failing step
- 本地复现：跑那个具体 audit 命令
- 修代码 → 重新 commit + tag（删除失败的 tag 重打）

### Step 6 — ⚠️ Packages 页 verify 实物（**强制，不能跳**）

打开 https://github.com/NancyZeng0210/TVU-Design-System/packages

**必须看到**：
- `@nancyzeng0210/tvu-design-system` package
- 顶部 latest version 显示 `0.2.0`（不是 0.1.3）
- 时间戳是刚才 publish 的

**这一步不能跳的原因**：v0.1.0 / v0.1.1 silent fail 的根因。CI green 只代表 step exit 0，**不代表 registry 实际接受**。只有 Packages 页实物 = 真正 published。

---

## 3. Publish 完成后的 wrap-up

### 3.1 STATUS.md "当前版本" 段更新

```markdown
## 当前版本：v0.2.0（✅ published & verified）

| 项 | 值 |
|---|---|
| 已 publish | ✅ 2026-05-14 → GitHub Packages [`@nancyzeng0210/tvu-design-system@0.2.0`](https://github.com/NancyZeng0210/TVU-Design-System/packages) (CI run #<N> green; Packages 页实物 verified — "0.2.0 Latest") |
| 包名 | `@nancyzeng0210/tvu-design-system@0.2.0` |
| Docs site | 20 toggle-aware pages（新增 Chart）|
| Release 流程 | changesets + tag-triggered CI + audit gate（**9 strict / 0 warn-only**）|
```

### 3.2 写 release retrospect

`docs/internal/retrospection/2026-05-14-v0-2-0-release.md`：
- CI run number + Packages 页实物 verified ✅
- 新引入 dep（chart.js + vue-chartjs）peerDep 设计验证
- 任何 release 过程中暴露的问题（如有）

按 STATUS.md "Retrospection 触发判断" §「阶段性 release」必写。

### 3.3 Update memory（如有新通用 pattern）

候选：
- Chart.js peerDep 模式（如未来其他可视化 dep 复用）
- CSS-var 注入 Chart.js MutationObserver 模式（如其他动态主题组件复用）

不必硬塞 memory；只在「未来另一个 session 遇到类似选型会从中获益」时存。

---

## 4. 失败回滚

如 v0.2.0 publish 失败（CI fail / Packages 页未显示）：

1. **不要重打同 tag**（git tag 不可重用，npm 也不接同版本号重发）
2. 删 failed tag：
   ```bash
   git tag -d v0.2.0
   git push --delete origin v0.2.0
   ```
3. 修问题 → commit → 重新走 §2 step 4-5
4. 如已 partial publish（registry 接受了 broken artifact）→ 改 changeset 升 v0.2.1 patch 而不是修 v0.2.0

---

## 5. 今日 session 9（2026-05-13）累计已 push

不需要再 commit src/ 代码，本次发布只是 metadata + tag。

| commit | 关键内容 |
|---|---|
| 5a9d4ab7 | INFRA-F20 Playwright baseline 58 截图 |
| 5b39e886 | vitest 10 fixture drift fix |
| fa03b1ee + af61d18a + 98a85bd3 | INFRA-F26 extract idempotence |
| c2c17969 | INFRA-F29 normalize idempotence |
| 4f993a17 + 0d9332b6 + 716212ba + 2b1283b5 | INFRA-F21 v1 + polish husky pre-commit |
| bb32f374 + 96016f23 + 061a3e54 + 4f715141 | CANONICAL-011 D1/D2/D3 + baseline cascade + close |
| 444406a2 | BRIDGE-MOCKUP-004 close + audit:published-vs-code 升 strict |
| d4b6d902 | CANONICAL-011 prompt gap retrospect |
| wrap-up commit | STATUS bump + tracker sync + pickup file（本文件）|

---

## 6. Active 余量（v0.2.0 publish 后）

```
v0.1.x patches (3):  CANONICAL-007  BRIDGE-MOCKUP-001/002/003 (all blocked / 设计师 owner)
v0.2.x patches:      (待发现)
v1.0 major     (7):  Phase 6.3/6.4/6.6/6.7/6.8  BRIDGE-005  EXTRACT-006
Infrastructure (5):  F21-v2/v3/v4  F24  F25-docs-bg-contrast  (release-agnostic)
BRIDGE-MOCKUP-005 (designer-owner): chart palette figma 真源补完
```

下个 session 用户决策点：
- 推 F25 收尾 docs-page-bg-contrast audit 加 9th-or-10th strict gate？
- 等设计师补 BRIDGE-MOCKUP-001/002/003/005？
- 或起 v1.0 major（破坏性 API）路径？