尧图网页设计 
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 分支、交互式询问三类标签、填充模板、创建 PRcanary/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 exportNextjs-Vite: Add supportCLI: Fix automigrate issueArea对应的是仓库内的功能域如 CSF Factories、Nextjs-Vite 框架适配器、CLI 等Description 用一句话概括改动意图。这种格式的实战价值在于标题前缀让维护者在 PR 列表里即可按模块过滤问题也便于 changelog 聚合与检索。标签体系Category / CI / QA 三组标签各选其一Storybook 要求每个 PR 必须打上三组标签每组只选一个。这对应了模板中 Checklist for Maintainers 的要求PR 必须包含其中一个类别标签并通过ci:*标签声明要跑哪套沙箱通过qa:*标签声明发版期是否需要人工 QA。Category必填9 选 1标签含义是否进入 changelogbug修复错误行为是maintenance面向用户的维护性改动是dependencies升级/降级依赖是build内部构建/测试工具更新否cleanup小型代码清理否documentation纯文档改动否feature request新功能是BREAKING CHANGE破坏兼容性是other以上均不适用—其中build/cleanup/documentation三类的共同特征是不出现在发布 changelog 中——这一信息直接来自 PULL_REQUEST_TEMPLATE.md 的 Available labels 折叠区技能文档与其逐字对应。CI必填选 1标签含义ci:normal标准沙箱集合绝大多数代码改动的默认选择ci:merged合并后的更大沙箱集合ci:daily每日沙箱集合当改动影响 prerelease 沙箱、或钉在较旧框架/React 版本的沙箱时使用ci:docs纯文档改动配合documentation类别使用这组标签不是凭空设定的它与仓库源码直接挂钩。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展开normaldaily再展开merged因此默认ci:normal、影响面扩大到 prerelease/旧框架版本沙箱时升级到ci:daily的规则与源码中集合的嵌套设计完全吻合。QA必填选 1qa:needed/qa:skip这两个标签告诉发版团队在下一个 minor 版本发布前是否需要针对该 PR 做人工 QAqa:needed— 发布前必须有人工验证qa:skip— 无需逐 PR 人工 QA。技能文档给出了一套明确的启发式判断规则这是该规范中最具经验价值的部分用户明确要求发版前人工 QA →qa:needed属于一个整体 QA 的大项目的一部分不按 PR 逐个验证→qa:skip触碰路径处理、文件系统、或任何在 Windows 上可能出问题的代码 →qa:needed横跨多个模块、必须协同工作的复杂改动 →qa:needed位于中心/共享代码、高副作用风险的小改动例如共享 UI 的布局 CSS→qa:needed简单直接的小改动 →qa:skip拿不准 → 直接询问用户是否需要发版前人工 QAPR 正文逐字复制模板保留全部 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 --几个填写要点Closes #开头关联 issue 编号多个 issue 用 closes #1000, closes #1001 分开写模板注明所有 PR 提交到next分支除非仅针对当前发布分支——维护者会在发版流程中把 bug 与文档修复 cherry-pick 进main贡献者不必操心自动测试勾选在 stories / unit / integration / end-to-end 四个复选框上勾选实际覆盖的类型Documentation 小节若改动涉及文档更新、或废弃/移除功能需同步 MIGRATION.md则勾选对应项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 模板内部 UIInternal UIhttps://branch--635781f3500dd2c49e189caf.chromatic.com/?path/story/story_idReact Vite TS 沙箱https://branch--630511d655df72125520f051.chromatic.com/?path/story/story_id其中branch要替换为 Chromatic 归一化后的 slug特殊字符替换为连字符如feature/foo→feature-foostory_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 megh pr create \ --draft \ --base detected-base \ --title Area: Description \ --body $(cat EOF FILLED_TEMPLATE EOF ) \ --assignee me \ --label type,ci,qaPR 创建后open-pr技能还会询问是否需要触发 canary 发布canary/SKILL.md 说明了触发方式gh workflow run --repo storybookjs/storybook publish.yml --field prPR_NUMBER及 canary 版本号的预测格式0.0.0-pr-PR_NUMBER-sha-SHORT_SHA——这与 PR 模板中 Canary release 小节的说明一致。速查清单标题[Area]: [Description]Area 首字母大写、无空格连字符可用类别标签9 选 1bug/maintenance/dependencies/build/cleanup/documentation/feature request/BREAKING CHANGE/other注意build、cleanup、documentation不进 changelogCI 标签1 选 1默认ci:normal影响 prerelease 或钉住旧框架/React 版本的沙箱用ci:daily纯文档用ci:docs。对应沙箱集合定义见 sandbox-templates.tsQA 标签1 选 1按路径/文件系统/Windows 风险、跨模块复杂改动、共享代码高副作用 →qa:needed简单改动、整体 QA 的大项目 →qa:skip判断拿不准就问用户正文从 .github/PULL_REQUEST_TEMPLATE.md 逐字复制含 HTML 注释勾选自动测试类型Manual testing 必填且写给别的维护者自己先跑通一遍命令gh pr create --draft --title ... --body ... --label category,ci,qa永远 draft 起步目标分支提交到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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 分支、交互式询问三类标签、填充模板、创建 PRcanary/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 exportNextjs-Vite: Add supportCLI: Fix automigrate issueArea对应的是仓库内的功能域如 CSF Factories、Nextjs-Vite 框架适配器、CLI 等Description 用一句话概括改动意图。这种格式的实战价值在于标题前缀让维护者在 PR 列表里即可按模块过滤问题也便于 changelog 聚合与检索。标签体系Category / CI / QA 三组标签各选其一Storybook 要求每个 PR 必须打上三组标签每组只选一个。这对应了模板中 Checklist for Maintainers 的要求PR 必须包含其中一个类别标签并通过ci:*标签声明要跑哪套沙箱通过qa:*标签声明发版期是否需要人工 QA。Category必填9 选 1标签含义是否进入 changelogbug修复错误行为是maintenance面向用户的维护性改动是dependencies升级/降级依赖是build内部构建/测试工具更新否cleanup小型代码清理否documentation纯文档改动否feature request新功能是BREAKING CHANGE破坏兼容性是other以上均不适用—其中build/cleanup/documentation三类的共同特征是不出现在发布 changelog 中——这一信息直接来自 PULL_REQUEST_TEMPLATE.md 的 Available labels 折叠区技能文档与其逐字对应。CI必填选 1标签含义ci:normal标准沙箱集合绝大多数代码改动的默认选择ci:merged合并后的更大沙箱集合ci:daily每日沙箱集合当改动影响 prerelease 沙箱、或钉在较旧框架/React 版本的沙箱时使用ci:docs纯文档改动配合documentation类别使用这组标签不是凭空设定的它与仓库源码直接挂钩。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展开normaldaily再展开merged因此默认ci:normal、影响面扩大到 prerelease/旧框架版本沙箱时升级到ci:daily的规则与源码中集合的嵌套设计完全吻合。QA必填选 1qa:needed/qa:skip这两个标签告诉发版团队在下一个 minor 版本发布前是否需要针对该 PR 做人工 QAqa:needed— 发布前必须有人工验证qa:skip— 无需逐 PR 人工 QA。技能文档给出了一套明确的启发式判断规则这是该规范中最具经验价值的部分用户明确要求发版前人工 QA →qa:needed属于一个整体 QA 的大项目的一部分不按 PR 逐个验证→qa:skip触碰路径处理、文件系统、或任何在 Windows 上可能出问题的代码 →qa:needed横跨多个模块、必须协同工作的复杂改动 →qa:needed位于中心/共享代码、高副作用风险的小改动例如共享 UI 的布局 CSS→qa:needed简单直接的小改动 →qa:skip拿不准 → 直接询问用户是否需要发版前人工 QAPR 正文逐字复制模板保留全部 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 --几个填写要点Closes #开头关联 issue 编号多个 issue 用 closes #1000, closes #1001 分开写模板注明所有 PR 提交到next分支除非仅针对当前发布分支——维护者会在发版流程中把 bug 与文档修复 cherry-pick 进main贡献者不必操心自动测试勾选在 stories / unit / integration / end-to-end 四个复选框上勾选实际覆盖的类型Documentation 小节若改动涉及文档更新、或废弃/移除功能需同步 MIGRATION.md则勾选对应项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 模板内部 UIInternal UIhttps://branch--635781f3500dd2c49e189caf.chromatic.com/?path/story/story_idReact Vite TS 沙箱https://branch--630511d655df72125520f051.chromatic.com/?path/story/story_id其中branch要替换为 Chromatic 归一化后的 slug特殊字符替换为连字符如feature/foo→feature-foostory_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 megh pr create \ --draft \ --base detected-base \ --title Area: Description \ --body $(cat EOF FILLED_TEMPLATE EOF ) \ --assignee me \ --label type,ci,qaPR 创建后open-pr技能还会询问是否需要触发 canary 发布canary/SKILL.md 说明了触发方式gh workflow run --repo storybookjs/storybook publish.yml --field prPR_NUMBER及 canary 版本号的预测格式0.0.0-pr-PR_NUMBER-sha-SHORT_SHA——这与 PR 模板中 Canary release 小节的说明一致。速查清单标题[Area]: [Description]Area 首字母大写、无空格连字符可用类别标签9 选 1bug/maintenance/dependencies/build/cleanup/documentation/feature request/BREAKING CHANGE/other注意build、cleanup、documentation不进 changelogCI 标签1 选 1默认ci:normal影响 prerelease 或钉住旧框架/React 版本的沙箱用ci:daily纯文档用ci:docs。对应沙箱集合定义见 sandbox-templates.tsQA 标签1 选 1按路径/文件系统/Windows 风险、跨模块复杂改动、共享代码高副作用 →qa:needed简单改动、整体 QA 的大项目 →qa:skip判断拿不准就问用户正文从 .github/PULL_REQUEST_TEMPLATE.md 逐字复制含 HTML 注释勾选自动测试类型Manual testing 必填且写给别的维护者自己先跑通一遍命令gh pr create --draft --title ... --body ... --label category,ci,qa永远 draft 起步目标分支提交到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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考