Carbon 设计系统 PR 审查指南从四步流程到分类型审查清单的完整实践【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文以carbon-design-system/carbon仓库中的 docs/guides/reviewing-pull-requests.md 为主体结合仓库内 PR 模板、PublicAPI 快照测试、AVT/VRT 端到端测试、版本控制文档与样式指南等源码证据系统讲解该设计系统 monorepo 的 Pull Request 审查规范。读者既可把它当作 Maintainer 审查 PR 的检查清单也可作为 Contributor 提交 PR 前的自检手册掌握从「初始审查 → 功能验证 → 代码与 CI 校验 → 终审合并」的完整闭环以及针对 React、Web Components、Storybook、样式、CI、图标等不同变更类型的专项审查要点。文档定位与适用人群这份指南面向两类读者Maintainers维护者用它作为评估 PR 的起点与核对清单Contributors贡献者用它作为提交 PR 的内容清单让 PR 能更顺利地通过评审。文档本身刻意保持小而精它只作为评审的起点starting point并不会罗列评审中可能出现的每一个细节 nit并且文档要求自身内容尽可能保持精简因为篇幅越长越难被阅读吸收。这意味着评审的完整能力来自文档骨架 仓库中散落的专项文档版本控制、样式规范、开发者手册、发布流程等本文会把这些关联资料一并串起来。该文档明确说明它不会包含每次 PR 评审中可能出现的每一个小 nit 和细节作为起点使用即可。一、PR 审查的四步流程整体流程可以概括为四个阶段初始审查 → 功能测试 → 代码与 CI 校验 → 终审与合并准备。1. 初始审查Initial Review审查的第一步不是看代码 diff而是建立上下文阅读 PR 描述PR Body理解本次变更的整体范围。仓库强制要求 PR 必须使用并完整填写 PR 模板见 .github/PULL_REQUEST_TEMPLATE.md模板包含Closes #、{{short description}}、ChangelogNew / Changed / Removed 三段式、Testing / Reviewing如何验证该 PR 的步骤或清单以及完整的 PR Checklist。关联 Issue 与设计文档阅读关联的 Issue或设计规格来把握问题的根源与背景。从 PR 模板 可以看到贡献者在标记 Ready for Review 前需要确认的清单包括逐行审查 diff、更新文档与 Storybook 示例、遵循 v12 迁移文档要求、编写覆盖变更的通过测试、处理 a11y 影响、测试跨浏览器一致性、以及确认代码已准备好评审且状态检查应可通过。任何未完成项都应勾掉或把 PR 转为 Draft。2. 功能测试Functional Testing功能验证是改得对不对的第一道闸门Deploy Preview打开部署预览按照 PR 描述中Testing/Reviewing一节所述的方式测试变更。本地测试可选必要时使用ghCLI 在本地检出 PR然后运行yarn yarn build也可以只构建受影响的包以节省时间yarn lerna run build --scopecarbon/{packageName} --include-dependencies这与仓库使用的 Lerna Yarn workspaces 单仓monorepo结构一致见根目录 lerna.json--scope限定到某个包、--include-dependencies连带构建其依赖是评审大仓库时非常实用的技巧。3. 代码与 CI 校验Code CI VerificationCode Review按变更类型对照后文的 Items to Review by Change-Type。CI Checks确认所有 CI 检查通过若有检查失败查看日志并给出建议例如更新测试或快照并打上status: failing CI ‍♂️标签若怀疑是误报false positive可重新运行re-run或重启该检查。仓库根目录下的 .github/workflows 目录中实际运行着约 30 个工作流包括ci.yml、codeql-analysis.yml、dco.ymlDeveloper Certificate of Origin 校验、issue-triage.yml、stale.yml、release.yml、version.yml、version-patch.yml以及针对 v10 的v10-ci.yml等覆盖了 CI、发布、版本号生成、代码扫描等环节审查 PR 时这些工作流的状态都是需要关注的。4. 终审与合并准备Final Review Merge Preparation提交评审意见时在 Files Changed 页面使用三种评审选项Comment汇总反馈或提出澄清性问题Approve标记 PR 已批准Changes Requested阻止合并直到要求的修改完成。判断是否需要设计评审Design Review当变更影响 UI 或视觉效果例如布局、样式、组件或用户交互时PR 需要设计评审对于外部贡献者的 PRCarbon 团队开发者同样需要按此规则判断是否需要进行设计评审若需要设计评审指派一位设计师 reviewer并添加status: visual review 标签。评审后的动作视情况添加status: one more review 标签若需要设计评审只有设计师批准后才可移除status: visual review 标签设计师优先操作设计师批准后开发者也可以移除批准数量要求需要设计评审的 PR2 个开发者批准 1 个设计批准不需要设计评审的 PR2 个开发者批准。所有必需批准完成后移除所有status标签添加status: ready to merge 标签并排队合并只有在所有必需批准都齐备的情况下才允许启用Enable auto-merge禁止在合并按钮变绿仅 CI 通过时就直接使用Enable auto-merge或Merge when ready——必须等到所有必需批准完成。这一系列的status标签规则与仓库中的 .github/labeler.yml 自动打标机制以及metrics-merge-rate.yml、metrics-repo-stats.yml等度量工作流共同构成了 PR 状态治理体系保证合并动作的合规性。二、按变更类型的专项审查清单文档将审查清单按变更类型拆分覆盖了设计系统单仓中最常见的八类变更。1. PublicAPIsemver变更快照与版本控制将 PublicAPI 快照变更与 版本控制文档 对照验证任何 PropTypes/Types 变更是否向后兼容——放宽widening是允许的收窄narrowing属于破坏性变更。测试确保测试通过若快照已过时用yarn test -u更新并推送变更。仓库证据packages/react/tests/PublicAPI-test.js 就是这份快照机制的实现——它通过遍历组件所有的 PropTypes 并把输出存入快照文件来追踪carbon/react的整个公共 API。文件头部的注释明确写道如果快照失败说明你更改了组件公共 API增加/移除 prop type这要求对应的 semver 变更测试的目的就是让你意识到该变更需要相应的 semver 版本号变化。结合 docs/guides/versioning.md 中的 semver 对照表Carbon 对carbon/react的约定是变更类型semver bump组件类型/定义typings变更patch类型定义不绑定 semver新增组件 propminor废弃deprecate现有 propminor移除现有 propmajor现有 prop 类型变得更具体major现有 prop 类型变得更泛化minorPropTypes.func参数改变majorPropTypes.func增加参数minorPropTypes.func减少参数major这也是评审 PublicAPI 快照变更时判断该升major还是minor的直接依据。2. React 变更破坏性变更审查对稳定组件的删除或修改避免破坏既有功能。useEffect 使用谨记 You might not need an effect!删掉不必要的 effect确保依赖数组完整检查禁用 eslint 规则的抑制注释suppression comments是否合理确认缺失的依赖数组没有隐藏本应放在 render 函数中的逻辑验证 refs 没有被误当作依赖ref 不会触发重新渲染。useRef 使用使用可选链如ref?.current避免空指针问题。命令式代码避免使用命令式 DOM 查询如document.querySelector()优先使用 refs。服务端渲染SSR使用useWindowEvent替代window.addEventListener以适配 SSR优先使用useIsomorphicEffect而非useLayoutEffect。仓库证据在 packages/react/src 下useWindowEvent与useIsomorphicEffect被广泛应用于组件实现例如 Tabs、Popover、MultiSelect、Notification、Slider.Skeleton 等数十个文件这些就是该评审原则在真实代码中的落地。国际化将硬编码的可见文本labels、help text 等替换为适当的标记或字符串处理方式以支持 RTL从右到左语言。性能优化在合适处建议使用useCallback或useMemo。3. Web Components 变更文档中该部分当前标注为TBD待补充说明这份指南仍在演进中。对应地仓库中carbon/web-components包拥有独立的测试体系见 packages/web-components/tests 与web-test-runner.config.mjs、playwright.config.js审查 Web Components 变更时可参考这些测试配置作为补充依据。4. Storybook 变更文档准确性确认组件 API 的变更已正确反映在 Storybook 文档页的 component api 表格中必要时更新component.mdx文件。测试故事清理合并前删除任何测试或临时的 stories。Args/Controls 功能确保 stories 的 args/controls 完全可用。仓库中 packages/react/code-connect、packages/web-components/code-connect 以及各包src下的.mdx文档即 Storybook 内容的主要载体评审时需同步核对。5. 测试变更Testing Changes测试实践优先使用screen而非container进行查询使用可访问性查询accessible queries提升测试可靠性。覆盖率单元测试需覆盖新 props、功能变更以及组件基线行为用AVT 测试Automated accessibility Visual Tests自动化可访问性与视觉回归测试验证可访问性变更用VRT 测试Visual Regression Testing视觉回归测试覆盖默认 story 及其他组件状态/stories。仓库证据在 e2e/components 目录下每个组件都有对应的*-test.avt.e2e.js文件如 Button-test.avt.e2e.js它们基于 Playwright见根目录 playwright.config.js 与 jest.e2e.config.js通过visitStory访问 Storybook story 并在avt描述的用例中检查组件状态与可访问性例如avt-default-state、avt-keyboard-nav等测试用例。6. 样式变更Style Changes废弃变量确认没有使用已废弃的变量如$layout。间距与尺寸使用 spacing tokens间距令牌代替魔法数字magic numbers。仓库 docs/style.md 的 Avoid magic numbers 一节有详细说明——魔法数字是因为碰巧能用而使用的值应改用 spacing tokens、contextual layout tokens 或其他设计令牌体系中的值。CSS 逻辑属性始终使用 CSS 逻辑属性logical properties而非top、left、margin-left等固定方向属性以适配 RTL 等书写模式。前缀与模块使用确保应用了#{$prefix}验证依赖的样式模块被正确导入例如 Tooltip 样式依赖 Popover 样式。跨浏览器测试在主流浏览器Chrome、Firefox、Edge、Safari、Opera中查看变更使用 Storybook 的 viewport 宽度工具栏选项确保在每个主要断点breakpoint下工作正常。这与仓库 packages/styles/scss 中大量使用#{$prefix}与设计令牌的 SCSS 实现一致如 packages/styles/scss/_config.scss。7. 工作流 / CI 变更Workflow/CI Changes将第三方 actions固定到完整长度的 commit SHA提升供应链安全避免使用易被篡改的 tag 引用所有工作流修改应由**仓库管理员repo admin**审查。8. 图标变更Icon Changes发生图标变更时遵循 开发者手册 中Working with icons and pictograms一节的流程。该手册对应章节位于 docs/developer-handbook.md 的### Working with icons and pictograms。仓库中图标资产的源文件位于 packages/icons/src约 2800 个 SVG与 packages/pictograms/src图标元数据分类、废弃状态则由 packages/icons/icons.yml、packages/icons/categories.yml 维护。三、与发布流程的衔接PR 审查通过并合入main之后变更会进入 发布流程release.md。Carbon 采用基于时间的发布模型每两周一次稳定minor版本minor前数天发布 prerelease如v11.2.0-rc.0patch按需发布。发布过程由 version.yml 自动生成版本号 PR、release.yml 自动发布期间使用chore(release): vX.Y.Z约定提交与 git tag 标记发布提交。因此PR 审查阶段对 semver 变更的判断尤其是 PublicAPI 快照对应的major/minor/patch判定会直接影响后续版本的发布等级——这也是为什么文档把快照与版本控制对照列为 PublicAPI 变更审查的第一要务。四、贡献者视角让 PR 顺利通过评审的要点汇总综合整份指南Contributor 在提交 PR 前应自查填写完整 PR 模板关联 Issue 编号、变更描述、New/Changed/Removed 三段式 changelog、测试/评审步骤、逐项 Checklist遵守 semver 规则PropTypes 只放宽不收窄破坏性变更必须走majorPublicAPI 快照用yarn test -u更新并随 PR 提交React 代码规范避免不必要的 effect、使用可选链访问 ref、避免命令式 DOM 查询、SSR 友好useWindowEvent/useIsomorphicEffect、文本可国际化RTL 支持、需要时用useCallback/useMemo测试完备用screen 可访问性查询编写单元测试覆盖新 props 与基线行为a11y 变更配 AVT 测试视觉变更配 VRT 测试样式规范不使用废弃变量与魔法数字、使用 spacing tokens 与 CSS 逻辑属性、应用#{$prefix}、正确导入依赖样式模块、跨浏览器与各断点验证Storybook 同步更新 component API 表格与component.mdx删除测试故事保证 args/controls 可用CI 全绿确认 CI 通过快照类测试失败时更新快照而不是忽略。结语Carbon 的 PR 审查指南体现了一个大型设计系统 monorepo 的质量管控思路流程上分层把关初始 → 功能 → 代码/CI → 终审合并内容上按变更类型精准设防semver、React、样式、测试、CI、图标。它并非一份面面俱到的 nit 清单而是一个起点框架——配合仓库中的 PR 模板、版本控制文档、PublicAPI 快照测试、样式指南 与 开发者手册 共同使用即可覆盖从提交、评审到合并、发布的完整质量闭环。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考