Zulip 提交信息Commit Message规范从 SKILL 模板到 gitlint 自动校验的完整实践指南【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip本指南系统讲解 Zulip 项目统一的提交信息commit message格式规范。该规范源自仓库 .claude/skills/commit-message/SKILL.md被明确要求在编写或改写任何提交信息时使用Use whenever writing or rewording any commit message适用于所有向 Zulip 提交代码的开发者。读完本文你将掌握 Zulip 提交信息的完整格式模板、摘要与正文的写作要点、Issue 关联语法以及仓库中 gitlint 自动校验规则的底层实现从而写出规范、可追溯、易 review 的提交信息。一、提交信息的整体格式模板Zulip 提交信息由两部分组成摘要summary与正文description。其统一模板如下直接引自 SKILL.mdsubsystem: Summary in 72 characters or less. The body explains why and how. Include context that helps reviewers and future developers understand your reasoning, analysis, and verification of the work above and beyond CI, without repeating details already well presented in the commit metadata (filenames, etc.). Explain what the change accomplishes and why it wont break things one might worry about. Line-wrap at 68-70 characters, except URLs and verbatim content (error messages, etc.). Fixes #123.模板要点逐条拆解第一行是摘要由subsystem:前缀和一句 72 字符以内的总结构成空一行后是正文正文解释为什么why和怎么做how为 reviewers 和未来的开发者提供推理、分析与验证信息但不要重复提交元数据中已经体现的细节如文件名等行宽正文每行控制在 68–70 个字符URL 和逐字引用的内容如报错信息例外可以超宽末尾关联 Issue如Fixes #123.用最终段落固定格式关联并关闭问题。二、摘要Summary的写法规范1. 冒号前的小写子系统前缀冒号前是小写的、对该子系统或功能的简短提示a lower-case brief gesture at subsystem or feature可以用子系统名如nginx配置也可以用功能名如compose指消息输入框 compose box。官方示例compose: Fix cursor position after emoji insertion. nginx: Refactor immutable cache headers.反例Bad examplesFix bug Update code gather_subscriptions was broken2. 摘要必须以句号结尾摘要是一句完整句子以句号.结束示例compose: Fix cursor position after emoji insertion.从仓库 .gitlint 的配置可以看到这条规范被强制为两条机器可校验的规则[title-match-regex] regex^(.:\ )?[A-Z].\.$ [title-max-length] line-length72title-match-regex要求摘要要么以子系统:开头冒号后跟空格且其后首字母大写要么没有前缀无论哪种情况都必须以句号结尾title-max-length将摘要长度硬性限制在 72 字符以内与 SKILL.md 模板中 Summary in 72 characters or less 完全对应。3. 摘要动词必须使用祈使语气SKILL.md 强调摘要句式规范仓库则在 tools/lib/gitlint_rules.py 中用自定义 gitlint 规则ImperativeMood规则 IDZ1名为title-imperative-mood做了自动强制规则会剥离子系统:前缀取第一个单词若该词命中内置的时态词表TENSE_DATA覆盖 add、allow、fix、change、rename、refactor、remove、update 等常用动词就报错并提示对应的祈使形式。例如错误写法gather_subscriptions: Fixed exception handling bad input.会被提示改为Fix而Fixing、Fixes同理会被纠正为Fix。这意味着在 Zulip 中摘要动词必须是祈使语气这是被 CI 与本地 hook 双重强制的要求而不只是风格建议。三、正文Body的写作要求正文是提交信息中解释为什么与如何的部分。SKILL.md 模板要求正文包含能帮助 reviewers 和未来开发者理解的上下文包括你的推理、分析和验证其效果要超越 CI 本身。仓库 docs/contributing/commit-discipline.md 对正文写作给出了更细致的指引可归纳为解释动机与安全性说明该改动完成了什么以及为什么它不会破坏人们可能担心的东西例如删除函数参数时正文应说明删除该参数是安全的因为它始终为 False为 reviewer 提供一条可验证的推理链提供背景上下文推荐采用Previously, when X happened, this caused Y...的叙事模式描述负面后果不要复述 diff 显而易见的内容不要列出被修改的文件名、函数名清单不要写我更新了测试之类的事实——每个提交都被默认要求更新测试与文档避免个人过程叙述不要写First I tried XI changed Y这类过程流水账格式要求正文与摘要之间必须有空行否则 GitHub 等工具会错误渲染正文使用完整句子和段落段间用空行分隔检查拼写与语法错误因为提交信息是重要的技术写作英语错误会分散 reviewer 的注意力。四、Issue 关联语法Linking IssuesSKILL.md 明确规定了在提交信息中关联 GitHub Issue 的三种写法写法效果Fixes #123.合并后自动关闭该 IssueFixes part of #123.不会关闭Issue适用于部分修复Partially fixes #123.禁止使用——GitHub 会忽略 partially仍会关闭 Issue多提交multi-commitPR 的使用策略前面的提交用Fixes part of #123.最后一个提交用Fixes #123.。此外提交信息末尾还可以按需添加致谢行例如空行之后Co-authored-by: Greg Price gregzulip.com以及Reported-by:、Debugged-by:、Suggested-by:等备注Zulip 一般不用后者。注意 提及-mention不应出现在提交信息中它既不会通知被提及者也会污染提交历史要通知他人请放在 PR 讨论里。五、仓库中的自动校验实现gitlint 配置与 hookZulip 不只把规范写在文档里还通过 gitlint 将其固化为机器校验。核心配置在 .gitlint[general] ignoretitle-trailing-punctuation, body-min-length, body-is-missing extra-pathtools/lib/gitlint_rules.py [title-match-regex] regex^(.:\ )?[A-Z].\.$ [title-max-length] line-length72 [body-max-line-length] line-length76逐项解读ignoretitle-trailing-punctuation, body-min-length, body-is-missing跳过 gitlint 自带的标题尾标点正文最小长度正文缺失三项内置检查——因为这些已由自定义规则和项目约定接管例如正文是否必要由开发者自行判断SKILL 模板允许无正文的最小提交extra-pathtools/lib/gitlint_rules.py加载仓库自定义规则即前述的祈使语气检查title-match-regex/title-max-length强制前缀 大写开头 句号结尾与 72 字符上限body-max-line-length正文每行上限 76 字符比 SKILL.md 建议的 68–70 略宽松为 URL 与逐字内容留出余地但与 docs 中链接可以更长可忽略 gitlint 对此的抱怨的说法相呼应。提交信息 hook 链路仓库通过 tools/setup-git-repo 脚本把两个 Git hook 软链到.git/hooks/for hook in pre-commit commit-msg; do ln -snf ../../tools/$hook .git/hooks/ donetools/commit-msgcommit-msghook在每次提交时对提交信息运行gitlint若消息为空则跳过在 Vagrant 开发环境或普通环境VIRTUAL_ENV已激活下分别通过vagrant ssh或本机gitlint执行。命中规范问题时会打印警告WARNING: Your commit message does not match Zulips style guide.但 hook 始终返回 0不阻塞提交只做提示。tools/pre-commitpre-commithook对暂存区cached中变更的文件运行tools/lint显式--skipgitlint避免重复同样不阻断提交。tools/commit-message-lint独立的批量检查脚本供本地或 CI 使用。它会解析 git remote 判断上游仓库计算git merge-base HEAD与 upstream/main及*.x维护分支之间的提交并对该区间提交统一运行gitlint --commits $base..HEAD即一次性校验你相对上游新增的所有提交信息。可见Zulip 的提交信息规范通过文档约定 gitlint 配置 自定义规则 双 hook CI 批量校验五层落地是完整可执行的工程实践。六、配套的提交纪律让规范真正生效规范的最终目的是配合 Zulip 遵循的 Git 项目提交纪律——每个提交是一个最小的连贯想法Each commit is a minimal coherent idea。仓库 docs/contributing/commit-discipline.md 给出了配套要求与本提交信息规范互补每个提交必须连贯coherent应能通过测试相关测试改动应放在同一提交中而非单独修复上个提交破坏的测试不应让 Zulip 变差例如只加前端无后端支撑是不被允许的应能独立安全部署否则须在提交信息中详细说明可加[manual]标签错误处理应随触发它的代码一起提交TODO 注释应留在引入该问题的提交中。提交应尽量最小化minimal重构、加测试、重命名应做成可独立合并的预备提交移动代码应与功能改动分开两个不同的重构、两个不同的功能应分属不同提交。当提交信息读起来像若干不相关事项的清单时就该拆分成多个提交。保持干净的历史宁可提交偏小太细的提交之后容易 squash反过来则难提交不通过测试时应通过git commit --amend修正而不是叠加fix tests提交。写提交时可借助git rebase -i整理历史或使用先 stash 部分功能、完成重构并提交、再 unstash 继续的工作流。只有同时遵守提交粒度纪律与提交信息格式规范才能让git log成为项目最可靠的开发文档帮助维护者高效做 release 管理与回归排查。七、常见错误自查清单结合 SKILL.md 反例、gitlint 规则与 Zulip 官方文档提交前请自查摘要是否包含小写的子系统:前缀是否难以用 1–2 个词描述改动范围若是说明提交结构可能不合理摘要是否 ≤ 72 字符、以句号结尾、首词为祈使语气动词摘要是否避免使用bug、fix、refactor这类过于宽泛的词作为前缀正文与摘要之间是否有空行正文是否每行 ≤ 70 字符URL 除外正文是否解释了 why 与 how而非罗列 diff 中可见的文件名是否使用了正确的 Issue 关联写法Fixes #123./Fixes part of #123.是否误用了Partially fixes #123.最后设置 Zulip 的开发环境时运行tools/setup-git-repo安装 tools/commit-msg hook或运行 tools/commit-message-lint 进行批量检查即可在提交前自动发现大多数格式问题。【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
