Ant Design Commit Message 生成规范：基于 Git 暂存区的单行提交信息工作流

Ant Design Commit Message 生成规范基于 Git 暂存区的单行提交信息工作流【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design在多人协作的开源组件库中提交信息的质量直接影响 changelog 生成、问题回溯和自动化处理的准确性。Ant Design 仓库在.agents/skills/commit-msg/目录下内置了一份面向 AI Agent 的 Commit Message 生成规范skill定义了“先读暂存区、再看仓库近期提交风格、最后归纳为一行”的完整工作流。读完本文你将掌握该规范的执行步骤、命令依据、type/scope 选择规则与边界情况处理方式并能在 ant-design 仓库中复现与仓库既有风格完全一致的单行 commit message。一、规范定位一个面向 Agent 的 Skill该规范以 Agent Skill 的形式存放于仓库中主文件SKILL.md定义目标、触发场景、基本规则、执行步骤与写法要求参考资料format-and-examples.md提供 antd 仓库近期提交风格参考、type/scope 示例与合并写法。skill 的 frontmatter 声明了触发条件当用户要求“写 commit message”、说“msg”且语境是 git 提交、说“写提交信息”或希望根据当前改动生成一句提交说明时使用。其核心目标是准确概括提交内容——基于当前 git 暂存区生成一行 commit message覆盖本次提交包含的全部改动保持仓库风格一致——优先贴近仓库已有提交习惯而不是机械套模板。核心原则一句话概括commit message 不是对 diff 的逐文件罗列而是对这次提交意图的压缩表达。先读暂存区再归纳再输出一行。二、三条基本规则规则一默认只看暂存区staged changes真正会被提交的是暂存区内容因此 message 的生成依据默认限定在 staged changes。只有当用户明确说“包含未暂存内容”或“按全部改动写”时才额外查看git diff。规则二必须先看仓库最近提交风格生成 message 前除了看暂存区还必须查看最近提交避免写出不符合仓库习惯的格式。这一点从 ant-design 仓库的实际 git 历史可以得到印证——当前仓库 HEAD 提交为refactor(Dropdown): simplify popup node normalization (#59216)这正是 format-and-examples.md 中所描述的type(scope): subject形态且 subject 使用小写祈使句开头。该参考资料还列出了近期提交中常见的写法例如fix(site): prevent duplicate API requests for doc contributorsfix(Splitter): set partially defined panel sizes correctlychore: bump antfu/eslint-config to 7.7.0site: fix ThemePreview copy button in dark themedocs: fix parenthesis typo in Form.useWatch typeci: skip persist image-snapshots从中可以归纳出仓库风格特征常用英文形式不单一既有type(scope): subject也有scope: subjectsite经常直接作为前缀使用。规则三默认只输出最终一行除非用户明确要求解释理由否则最终回复只给一行 commit message不附带分析、项目符号、代码块或引号也不加反引号。这样输出才能“直接拿去提交”。三、执行步骤与命令依据规范明确要求先获取信息再生成 message不要猜测也不要只凭文件名写。步骤 1读取 git 状态、暂存区和最近提交建议执行的命令及各自作用git status --short # 确认哪些文件已 stage是否还有未 stage 内容 git diff --cached --stat # 快速把握改动范围 git diff --cached # 查看实际提交内容这是生成 message 的依据 git log --oneline -10 # 检查仓库最近的提交风格、语言、type/scope 习惯其中git diff --cached是唯一的实质依据git status --short用于防止遗漏已 stage 但未纳入考虑的内容。步骤 2先判断是否能生成若暂存区为空不要编造 message明确说明当前没有 staged changes无法基于提交区生成准确的一行 commit message。步骤 3归纳这次提交的主语义根据git diff --cached的结果做三件事找出本次提交的主要目的新功能、修 bug、文档修改、重构、测试、脚本或依赖调整等识别主要影响范围组件、目录、站点、脚本、文档等若包含多个文件或多类小改动用一个更高层级的概括覆盖全部不要逐项拼接成长句。步骤 4对齐 ant-design 仓库风格优先模仿仓库近期写法。对于 ant-design通常可见这些形式fix(Component): ...docs: ...chore: ...ci: ...site: ...注意两点不要强行把所有提交都写成严格的 Conventional Commits如果仓库已有更自然的写法优先贴近仓库已有习惯。若改动主要在site可用site: ...若是明确的修 bug也可用fix(site): ...。步骤 5生成一行 message输出应同时满足一行、覆盖全部 staged changes、简洁、与仓库风格一致、可直接拿去提交。四、写法要求标题格式、type 与 scope标题格式优先使用以下两种之一type(scope): subject或scope: subject例如fix(Table): correct pagination when data is emptydocs: update FAQ link in issue templatesite: add one-click copy theme code button标题规则使用祈使语气写现在要做什么如add/fix/update首字母不要大写除非scope是组件名如Button、Table结尾不要句号尽量控制在72 个字符内不要出现WIP、misc、update files这类空泛表述。type 选择type适用场景feat新功能fix修 bugdocs文档、说明、示例文字refactor重构不引入新功能也不是修 bugtest测试新增或调整chore依赖、脚本、工程杂项ciCI 配置 / CI 流程改动site文档站、官网、展示层交互不确定时的判断优先级有用户可见行为修正优先fix只是文字、示例、说明更新优先docs只是工具链、依赖、脚本调整优先chore。scope 选择改动集中在单个组件时用组件名如Button、Table、Form、DatePicker改动集中在目录或模块时用site、scripts、docs、theme宽 scope 可用components若没有明确 scope允许省略。何时用哪种 type参考资料中的细化规则fix(Component)适用于组件行为修正例如交互不符合预期、边界状态显示错误、类型或逻辑错误影响使用。示例fix(Table): correct pagination when data is empty、fix(Form): preserve validate status after reset。docs适用于只改文档文字、改 demo 说明、改 README/FAQ/注释示例。示例docs: update FAQ link in issue template、docs(Button): clarify loading demo description。site适用于文档站或官网层面的改动例如首页展示、文档页交互、暗色模式下的展示问题。示例site: add one-click copy theme code button、site: fix ThemePreview copy button in dark theme。chore适用于依赖升级、lint 规则调整、脚本维护、非业务逻辑的工程改动。示例chore: bump biomejs/biome from 2.4.5 to 2.4.6、chore(scripts): update release helper。多改动合并为一行的写法暂存区同时包含多种小改动时用更高层级的概括覆盖全部改动组合推荐写法多个组件小修补chore(components): clean up styles and types文档 代码示例docs: update Button demo and README修 bug 同时调样式fix(Table): pagination and styling站点多个交互点一起调整site: refine theme preview interactions参考资料中还给出了从输入到输出的完整映射示例输入git diff --cached显示只改了components/button/demo/loading.md里一段说明 → 输出docs(Button): update loading demo description输入暂存区包含 Table 的 type 修正、一处样式、一个 test 文件 → 输出fix(Table): adjust pagination types, styles and test输入仅改了一个脚本文件 → 输出chore(scripts): update xxx script输入首页主题预览和复制按钮一起调整 → 输出site: refine theme preview copy interactions。五、边界情况处理多类改动混在一起如果 staged changes 混合了文档、样式、类型、小修复等内容优先找主目的如果没有单一主目的用更上层的概括目标是“诚实地覆盖全部改动”不是把每个点都塞进标题。提交内容过于分散若暂存区包含明显不相关的多组改动仍然给出一个尽量诚实的一行 message不要假装这些改动只有一个很具体的目的可使用较宽的概括如chore(components): clean up styles, types and docs。六、禁止事项清单规范明确列出了六条禁止行为可作为质量检查清单不读取git diff --cached就写 message只根据文件名猜测内容只描述部分文件或部分改动忽略其它已 stage 内容输出多行说明把分析当成 commit message为了套格式而违背仓库已有风格写超过 72 个字符的冗长标题除非很难避免。七、与仓库其他 Agent 规范的关系这份 commit-msg skill 并非孤立存在它位于.agents/skills/目录下的一组 Agent 工作流中与以下规范构成完整的提交—发布协作链路create-pr创建 PR 的规范要求基于分支相对基线的全部改动生成 PR并严格使用仓库自带模板其中明确 PR 标题固定使用英文。AGENTS.md项目开发指南其 PR 规范要求标题格式为类型: 简短描述如fix: fix button style issues in Safari browser并约定分支命名规范feat/...、fix/...、docs/...、refactor/...。commit message 中的 type/scope 选择与这些命名体系是一脉相承的。changelog、version-release 等 skill 则负责发布侧的更新日志整理AGENTS.md 中专门有一节 Changelog 规范约束CHANGELOG.en-US.md/CHANGELOG.zh-CN.md的条目格式。从这套规范的结构可以看出commit message 是“提交意图”的压缩表达PR 标题是“分支意图”的压缩表达二者都以英文、小写祈使句、type前缀为共同风格基底而 changelog 则面向用户感知层面三者各取所需、互不混用。八、快速自查清单在 ant-design 仓库中执行本规范时可按以下顺序自查是否执行了git status --short、git diff --cached --stat、git diff --cached、git log --oneline -10四条命令暂存区是否为空若为空是否直接拒绝生成而非编造message 是否覆盖了全部staged changes而非只挑显眼的文件是否贴近仓库近期风格type(scope): subject或scope: subject英文祈使句scope 为组件名时首字母大写长度是否控制在 72 字符内且无WIP/misc/update files等空泛表述最终回复是否只有一行不带引号、反引号或解释掌握这套工作流后无论是人工提交还是由 Agent 代为提交产出的 commit message 都能与 ant-design 仓库既有的提交风格保持一致并为后续的 changelog 生成与版本发布提供可靠的信息基础。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考