Storybook 规范化 PR 实战：标题格式、Category/CI/QA 三类标签体系与 Draft PR 工作流

Storybook 规范化 PR 实战：标题格式、Category/CI/QA 三类标签体系与 Draft PR 工作流

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook

本文基于 Storybook 仓库中的 PR 创建技能文档（.claude/skills/pr/SKILL.md 指向 pr/SKILL.md）及其配套的 PR 模板（.github/PULL_REQUEST_TEMPLATE.md），完整拆解 Storybook 社区提交 Pull Request 的规范：[Area]: [Description]标题约定、Category / CI / QA 三组标签的选择规则、必须"逐字复制"的 PR 正文模板与手工测试（Manual testing）要求，以及gh pr create的 Draft 提交命令。读完你可以按 Storybook 维护者的标准流程，写出一个能正确触发沙箱 CI、满足发版 QA 要求的规范 PR。

技能定位：为 Agent 与贡献者定义的 PR 规范

.claude/skills/pr/SKILL.md本身只有一行指针内容：

@../../../.agents/skills/pr/SKILL.md

即 Claude 侧的技能文件直接引用了 pr/SKILL.md，其 Frontmatter 声明了技能的使用时机与允许的工具：

name: pr description: Creates a pull request following Storybook conventions. Use when creating PRs, opening pull requests, or submitting changes for review. allowed-tools: Bash, Read

从仓库结构看，这是一套面向 AI Agent 的"技能（skill）"体系，pr技能定义了 PR 的核心规范，周围还有若干协作技能：

• open-pr/SKILL.md：从当前分支发起 Draft PR 的完整工作流（探测 base 分支、交互式询问三类标签、填充模板、创建 PR）；
• canary/SKILL.md：为 PR 触发 canary 版本发布；
• update-pr-description/SKILL.md：将 PR 标题/描述与其实际改动做比对并迭代修正；
• handle-pr-comments/SKILL.md：逐条处理 PR 评审意见。

pr技能是这一族技能中"规范本体"——例如open-pr技能明确写道："Title:[Area]: [Description]— see theprskill for format and examples."。下面按原技能文档的四个部分（Title format、Labels、PR body、Command）逐一展开。

PR 标题格式：[Area]: [Description]

技能文档对标题的约定非常严格：

[Area]: [Description]

• Area 首字母大写，且不含空格（允许使用连字符）；
• 官方给出的示例：
  • CSFFactories: Fix type export
  • Nextjs-Vite: Add support
  • CLI: Fix automigrate issue

Area对应的是仓库内的功能域（如 CSF Factories、Nextjs-Vite 框架适配器、CLI 等），Description 用一句话概括改动意图。这种格式的实战价值在于：标题前缀让维护者在 PR 列表里即可按模块过滤问题，也便于 changelog 聚合与检索。

标签体系：Category / CI / QA 三组标签各选其一

Storybook 要求每个 PR 必须打上三组标签，每组只选一个。这对应了模板中 "Checklist for Maintainers" 的要求：PR 必须包含其中一个类别标签，并通过ci:*标签声明要跑哪套沙箱，通过qa:*标签声明发版期是否需要人工 QA。

Category（必填，9 选 1）

其中build/cleanup/documentation三类的共同特征是"不出现在发布 changelog 中"——这一信息直接来自 PULL_REQUEST_TEMPLATE.md 的 Available labels 折叠区，技能文档与其逐字对应。

CI（必填，选 1）

这组标签不是凭空设定的，它与仓库源码直接挂钩。PR 模板的 Maintainers 检查项写明：

make sure to addci:normal,ci:mergedorci:dailyGH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found incode/lib/cli-storybook/src/sandbox-templates.ts

在 sandbox-templates.ts 中可以看到三套集合的真实定义：

export const normal: TemplateKey[] = [ ... ] // L1251 export const merged: TemplateKey[] = [ // L1283 ...normal, ... ] export const daily: TemplateKey[] = [ // L1295 ...merged, ... ] export const templatesByCadence = { normal, merged, daily }; // L1320

从源码结构看，三套集合是逐层包含关系（merged展开normal，daily再展开merged），因此"默认ci:normal、影响面扩大到 prerelease/旧框架版本沙箱时升级到ci:daily"的规则与源码中集合的嵌套设计完全吻合。

QA（必填，选 1）：qa:needed/qa:skip

这两个标签告诉发版团队在下一个 minor 版本发布前是否需要针对该 PR 做人工 QA：

• qa:needed— 发布前必须有人工验证；
• qa:skip— 无需逐 PR 人工 QA。

技能文档给出了一套明确的启发式判断规则（这是该规范中最具经验价值的部分）：

• 用户明确要求发版前人工 QA →qa:needed
• 属于一个整体 QA 的大项目的一部分（不按 PR 逐个验证）→qa:skip
• 触碰路径处理、文件系统、或任何在 Windows 上可能出问题的代码 →qa:needed
• 横跨多个模块、必须协同工作的复杂改动 →qa:needed
• 位于中心/共享代码、高副作用风险的小改动（例如共享 UI 的布局 CSS）→qa:needed
• 简单直接的小改动 →qa:skip
• 拿不准 → 直接询问用户是否需要发版前人工 QA

PR 正文：逐字复制模板，保留全部 HTML 注释

技能文档对 PR body 的要求只有一句话，但执行细节很关键：

Read.github/PULL_REQUEST_TEMPLATE.mdfrom the repository root. Copy that templateEXACTLY, including all HTML comments (<!-- ... -->). Fill in the relevant sections based on the changes, but keep all comments intact.

也就是说，正文必须基于 .github/PULL_REQUEST_TEMPLATE.md原样复制，包括所有 HTML 注释占位，然后只填写对应小节。该模板的完整骨架如下：

Closes # <!-- If your PR is related to an issue, provide the number(s) above; ... --> ## What I did <!-- Briefly describe what your PR does --> ## Checklist for Contributors ### Testing #### The changes in this PR are covered in the following automated tests: - [ ] stories - [ ] unit tests - [ ] integration tests - [ ] end-to-end tests #### Manual testing > [!CAUTION] > This section is mandatory for all contributions. ... ### Documentation - [ ] Add or update documentation reflecting your changes - [ ] If you are deprecating/removing a feature, make sure to update MIGRATION.MD ## Checklist for Maintainers - [ ] ... add `ci:normal`, `ci:merged` or `ci:daily` GH label ... - [ ] Declare whether manual QA will be needed ... through `qa:needed` or `qa:skip` - [ ] Make sure this PR contains **one** of the labels below: ... ### 🦋 Canary release <!-- CANARY_RELEASE_SECTION --> ... <!-- CANARY_RELEASE_SECTION --> <!-- BENCHMARK_SECTION --> <!-- BENCHMARK_SECTION -->

几个填写要点：

1. Closes #开头：关联 issue 编号，多个 issue 用 "closes #1000, closes #1001" 分开写；
2. 模板注明所有 PR 提交到next分支（除非仅针对当前发布分支）——维护者会在发版流程中把 bug 与文档修复 cherry-pick 进main，贡献者不必操心；
3. 自动测试勾选：在 stories / unit / integration / end-to-end 四个复选框上勾选实际覆盖的类型；
4. Documentation 小节：若改动涉及文档更新、或废弃/移除功能需同步 MIGRATION.md，则勾选对应项；
5. Maintainers 检查项保持不勾选：ci:*、qa:*和类别标签是通过 PR 标签体现的，模板中的维护者检查框留给维护者操作（配套的 update-pr-description/SKILL.md 也要求"更新复选框状态时不要删除 canary release 小节"）。

Manual testing：必填项，写给另一位维护者看

技能文档对 Manual testing 小节的要求最为具体：

• 必填，绝不允许留空。模板中甚至用> [!CAUTION]强调："This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly."
• 写给另一位维护者看，而不是记录你自己是怎么测的。模板注释原文："Do not describe how YOU tested the PR code, but how a separate maintainer should do so."
• 每一步应当：
  • 清晰、易跟随；
  • 尽量给出可直接复制粘贴的 shell 命令；
  • 明确说明要检查的预期行为（而不是"check it works"这种空话）；
  • UI 改动要链接到具体的 story；
  • 列出最可能回归、值得重点关注的区域。
• 先自己跑一遍这些步骤（"Verify your own steps first — run through them locally before opening the PR"）。

模板注释中给的标准示例风格：

1. Run a sandbox for template, e.g. `yarn task --task sandbox --start-from auto --template react-vite/default-ts` 2. Open Storybook in your browser 3. Access X story

附：Chromatic 预览链接格式

需要展示 UI 效果时，可以在 CI 完成后链接已发布的 Chromatic Storybook（技能文档特别提示：CI 跑完之前链接不可用，PR 刚打开时不要急着贴）。两种常用入口的 URL 模板：

• 内部 UI（Internal UI）：https://<branch>--635781f3500dd2c49e189caf.chromatic.com/?path=/story/<story_id>
• React Vite TS 沙箱：https://<branch>--630511d655df72125520f051.chromatic.com/?path=/story/<story_id>

其中<branch>要替换为 Chromatic 归一化后的 slug（特殊字符替换为连字符，如feature/foo→feature-foo），<story_id>为 story 路径（如example-button--primary）。

关于635781f3500dd2c49e189caf这个内部 UI 项目 ID，可以从仓库中印证：code/chromatic.config.json 里声明了"projectId": "Project:635781f3500dd2c49e189caf"，与技能文档中的链接前缀一致。

提交命令：始终以 Draft 模式创建 PR

规范的最后一步是命令本身——PR 必须始终以 draft 模式创建：

gh pr create --draft --title "<Area>: <Description>" --body "<FILLED_TEMPLATE>" --label "<category>,<ci>,<qa>"

其中<FILLED_TEMPLATE>是上文"逐字复制并填写"后的模板内容，--label的值是三组标签各选一项、以英文逗号拼接（如bug,ci:normal,qa:skip）。配套的 open-pr/SKILL.md 给出了等价的完整工作流版本：先git fetch origin并运行 detect-base-branch.sh 探测 base 分支（支持栈式 PR，回退到next），再用 heredoc 方式传多行 body、追加--base与--assignee @me：

gh pr create \ --draft \ --base "<detected-base>" \ --title "<Area>: <Description>" \ --body "$(cat <<'EOF' <FILLED_TEMPLATE> EOF )" \ --assignee @me \ --label "<type>,<ci>,<qa>"

PR 创建后，open-pr技能还会询问是否需要触发 canary 发布；canary/SKILL.md 说明了触发方式（gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>）及 canary 版本号的预测格式0.0.0-pr-<PR_NUMBER>-sha-<SHORT_SHA>——这与 PR 模板中 "🦋 Canary release" 小节的说明一致。

速查清单

1. 标题：[Area]: [Description]，Area 首字母大写、无空格（连字符可用）；
2. 类别标签（9 选 1）：bug/maintenance/dependencies/build/cleanup/documentation/feature request/BREAKING CHANGE/other，注意build、cleanup、documentation不进 changelog；
3. CI 标签（1 选 1）：默认ci:normal；影响 prerelease 或钉住旧框架/React 版本的沙箱用ci:daily；纯文档用ci:docs。对应沙箱集合定义见 sandbox-templates.ts；
4. QA 标签（1 选 1）：按"路径/文件系统/Windows 风险、跨模块复杂改动、共享代码高副作用 →qa:needed；简单改动、整体 QA 的大项目 →qa:skip"判断，拿不准就问用户；
5. 正文：从 .github/PULL_REQUEST_TEMPLATE.md 逐字复制（含 HTML 注释），勾选自动测试类型，Manual testing 必填且写给别的维护者，自己先跑通一遍；
6. 命令：gh pr create --draft --title ... --body ... --label "<category>,<ci>,<qa>"，永远 draft 起步；
7. 目标分支：提交到next分支（除非仅针对当前发布）。

这套规范的本质，是把"CI 触发策略、changelog 归类、发版 QA 排期"三个发版流程关注点前移到了 PR 创建时刻——贡献者打的三个标签，恰好就是后续 CI 选择沙箱集合、release 流程筛选 changelog 条目、QA 团队排定人工验证任务的直接输入。

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook