本文永久链接 – https://tonybai.com/2025/04/24/conventional-commits-guide

告别混乱Commit Log！用规范指引你写出有意义的提交！

大家好，我是Tony Bai。

Git的Commit Log (提交日志) 是项目演进的脉络，也是开发者之间沟通变更、追溯历史、理解代码演变的关键载体。然而，在实际开发中，我们常常面对杂乱无章、意义不明的提交信息——”fix bug”、”update code”、”wip” 等屡见不鲜。这些模糊的记录不仅让代码审查、问题排查和版本追溯变得异常困难，也阻碍了自动化流程的实施。Conventional Commits (约定式提交) 规范提供了一套清晰、简洁的指引，旨在将每一次提交都转化为有意义、结构化的信息单元，从而显著提升 Commit Log 的价值和可利用性。

在这篇文章中，我们将探讨Conventional Commits如何作为一项关键指引，帮助开发者和团队构建更清晰、更一致、更具信息量的提交历史。

1. Commit Log的困境：为何需要指引？

缺乏明确指引的Commit Log往往会陷入以下困境：

• 信息熵高，有效信息少: 大量模糊、随意的提交信息混杂在一起，难以快速定位关键变更或理解特定提交的目的。
• 沟通效率低下: 团队成员需要花费额外时间去解读他人的提交意图，代码审查效率降低。
• 历史追溯困难: 当需要回溯某个功能或 Bug 的引入/修复历史时，无结构的日志如同大海捞针。
• 自动化阻碍: 不一致、不可预测的提交信息使得自动化生成 Changelog、语义化版本控制（SemVer）等流程难以实现。

面对这些普遍存在的困境，业界亟需一套行之有效的规范来引导开发者记录更有价值的提交信息。这正是 Conventional Commits 规范所要解决的核心问题，它通过引入一套简洁而强大的结构化指引来实现这一目标。Conventional Commits并非强制性的铁律，而是一套强大的指引 (Guidance)，它通过引入轻量级的结构化约定，引导开发者在提交时思考并明确表达变更的性质、范围和影响。

2. Conventional Commits 核心指引：结构化的力量

该规范的核心指引体现在其简洁的提交信息结构上(如下所示)：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

遵循这项指引，每次提交都应包含以下关键要素：

• Type (类型): [必须遵循的指引] 表明提交的性质。规范定义了基础类型：

  • fix:：修复 Bug (对应 SemVer PATCH)。
  • feat:：引入新功能 (对应 SemVer MINOR)。
  • 鼓励扩展: 团队可以根据需要定义其他类型，如 build, chore(用于标记那些不涉及新特性或修复的常规维护工作，比如更新依赖项等), ci, docs, style, refactor, perf, test等，以适应具体工作流。这些扩展类型本身通常不直接影响版本号（除非包含破坏性变更）。

• Scope (范围): [可选但推荐的指引] 明确提交影响的代码库区域或模块，用括号包裹，如 feat(api): 或 fix(parser):。这极大地增强了信息的可定位性。

• Description (描述): [必须遵循的指引] 紧跟冒号和空格，用简洁的语言（推荐使用祈使句现在时）概括本次提交的核心变更内容。这是提交信息的“标题”。

• Body (正文): [可选指引] 当简短描述不足以说明时，提供更详细的上下文、动机和实现细节。与 Description 之间需空一行。

• Footer(s) (脚注): [可选指引] 提供元数据，如关联 Issue (Refs: #123)。特别重要的两个脚注指引：

  • BREAKING CHANGE: ：明确标示不兼容的 API 变更 (对应 SemVer MAJOR)。
  • INITIAL STABLE RELEASE: ：标记项目从 0.y.z 进入 1.0.0。

强调重要变更的简化指引： 规范还提供了 ! (紧跟 type 或 scope 之后) 和 !! 作为标记 BREAKING CHANGE 和 INITIAL STABLE RELEASE 的快捷方式，进一步简化遵循指引的实践。

为了更直观地理解这个结构，以下是一些典型的Conventional Commits示例：

• 简单的 Bug 修复:

fix: correct minor typos in documentation

• 带范围的新功能:

feat(lang): add Polish language support

• 使用 ! 标记破坏性变更:

refactor!(auth): remove deprecated JWT authentication method

注意：这里的 ! 表明这是一个破坏性变更，即使type是refactor。

• 包含详细正文和脚注的提交:

perf(api): improve user query performance significantly

Implemented a new indexing strategy for the users table and optimized
the SQL query execution plan. Initial tests show a 50% reduction
in average query latency under heavy load.

Reviewed-by: Alice <alice@example.com>
Refs: #456, #478

• 使用 !! 标记首次稳定版发布:

chore(release)!!: prepare for 1.0.0 stable release

Finalized documentation, updated dependencies, and ran comprehensive
end-to-end tests to ensure stability for the first major release.

INITIAL STABLE RELEASE: The project is now considered stable for production use.

通过遵循这些简单的指引，原本混乱的Commit Log就被转化为结构清晰、信息丰富的记录。

理解了 Conventional Commits 的核心结构和要素后，我们自然会问：遵循这项指引究竟能为开发者和团队带来哪些实实在在的好处？答案是多方面的，它能让原本静态、难以利用的 Commit Log “活”起来，释放出巨大的潜在价值。

首先，结构化的 type 和 scope 提升了可读性与可理解性，使团队能够快速筛选和定位信息，清晰的 description 和 body 阐述了变更的“什么”和“为什么”。

其次，一致的格式增强了团队沟通与协作，减少了误解，提高了代码审查和协作效率，使每一次提交都成为清晰的沟通。

此外，结构化的日志简化了历史追溯与问题排查，便于查找特定功能引入、Bug 修复或破坏性变更的源头。

最后，一个充满有意义提交的日志自然而然地成为自动化工具的理想输入，能够驱动自动化生成 CHANGELOG、自动化 SemVer 版本判断，以及基于提交类型触发不同的 CI/CD 流程。

认识到 Conventional Commits 带来的显著价值后，如何在日常开发中有效地遵循并最大化其效益，就成了一个关键问题。仅仅了解规范的语法是不够的，掌握一些最佳实践和深入的洞察，能帮助我们更好地将这项指引融入工作流。

3. 遵循指引的最佳实践与洞察

为了更好地应用Conventional Commits指引，以下几点值得关注：

• 原子化提交: 我们鼓励将复杂的变更分解为多个逻辑上独立的、遵循单一type的提交。这本身就是一种良好的 Git 实践，很多大厂的git commit规范以及代码review规范也是这么要求的。Conventional Commits 进一步强化了这一点。

• 选择最合适的Type: 当一次提交包含多种类型的变更时（虽然应尽量避免），选择最能代表其核心意图的 type，并在 Body 中详述其他变更。

• 祈使句现在时: 推荐使用如 “Add feature”、”Fix bug” 的风格撰写 Description，简洁、直接，如同给代码库下达指令。

• 利用工具辅助: 社区提供了丰富的工具（如Commitizen, commitlint等）来帮助开发者遵循规范格式，并在提交前进行校验，降低遵循指引的负担。

• 团队共识与逐步采纳: 引入规范需要团队达成共识。可以通过分享、讨论和使用工具逐步推广。

当然，良好实践的推广离不开工具的支持。幸运的是，围绕 Conventional Commits 已经形成了一个活跃的社区和丰富的工具生态系统，它们极大地降低了开发者遵循规范的门槛，让指引更容易落地。

4. 社区生态：工具让指引落地

Conventional Commits 的流行离不开活跃的社区和丰富的工具支持，它们帮助开发者轻松地将这项指引融入日常工作流：

• Commitizen: 交互式命令行工具，引导用户创建符合规范的提交信息。
• Commitlint: 用于校验提交信息是否符合规范，常与 Git Hooks (如 husky) 集成。
• IDE 插件: 主流 IDE (VS Code, JetBrains IDEs 等) 均有插件提供模板、补全和校验支持。
• 自动化版本与 Changelog 工具: 如 semantic-release, goreleaser/chglog等，它们消费符合规范的提交历史。

这两年基于大模型的辅助生成commit log的工具以及一些代码智能体应用(如Cursor等）也在规范git commit log方面起到了非常积极的作用，对于像我这样英语非母语但又喜欢以英文log提交的选手来说，这些工具大幅降低了我在纠结如何写commit log时的心智负担，给予了我很大的帮助。

5. 小结

总而言之，Conventional Commits 远不止一套冷冰冰的格式规则，它更像是一位贴心的向导，一项旨在将每一次提交都转化为宝贵信息资产的核心指引。它赋予我们结构化的力量，能够将困扰许多团队的混乱、低效的Commit Log，转变为清晰、一致且富有洞察力的项目演进历史——这对于提升代码可维护性、团队协作效率乃至自动化流程都至关重要。

现在，就将这项指引融入你的日常开发吧！ 让每一次git commit不再是随意的记录，而是对项目演进负责任的、有意义的贡献。

那么，你的团队是如何采纳和实践提交规范的？你在使用Conventional Commits或其他规范时，有什么独到的心得或踩过的“坑”吗？

非常期待在评论区看到你的分享与交流！

如果这篇文章让你觉得“提交信息确实应该更有意义”，请分享给你的同事或团队，一起提升代码库的 Commit Log 质量吧!

别忘了关注我，持续获取更多提升研发效能的实用技巧与深度解析。

6. 参考资料

• Conventional Commits v1.0.0 – https://www.conventionalcommits.org/en/v1.0.0/#specification

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格6$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
• Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

本文永久链接 – https://tonybai.com/2024/05/19/what-the-go-team-think-go-is

2024年的Google I/O大会如期而至。

这届大会的核心主旨毫无疑问是坚定不移的以AI为中心：Google先是发布了上下文长度将达到惊人的200万token的Gemini 1.5 Pro，然后面对OpenAI GPT-4o的挑衅，谷歌在大会上直接甩出大杀器Project Astra，视觉识别和语音交互效果，跟OpenAI的GPT-4o不相上下；接着，谷歌又祭出文生视频模型Veo硬刚Sora，效果酷炫，时长超过1分钟，打破Sora纪录。最后Google CEO劈柴宣布：谷歌搜索将被Gemini重塑，形态从此彻底改变！用户不再需要自己点进搜索结果，而是由多步骤推理的AI Overview来代办一切。

不过，除了AI之外，Google在移动、Web和Cloud几个平台方面也为开发者带来了诸多精彩的内容，这其中就包括由Google Cloud团队带来的“Profile-guided optimization with Go”的演讲：

注：目前，Go团队已归入Google Cloud团队管理。

该演讲由Cameron Balahan、Michael Pratt和James Ma三个人共同完成。其中长相颇似电影“源代码”主角杰克·吉伦哈尔的Cameron Balahan在演讲中首先登场，阐述了Go团队眼中的Go究竟是什么。

2022年，美国计算机学会通讯(Communications of the ACM)期刊2022年5月第65卷第5期将发表了一篇有关Go语言的综述类Paper：《Go编程语言与环境》，这篇文章由Russ Cox，Robert Griesemer，Rob Pike，Ian Lance Taylor和Ken Thompson等Go团队的大佬联合撰写，对10多年来Go演化发展进行了复盘，深入分析了那些对Go的成功最具决定性的设计哲学与决策，这算是Go团队第一次阐述Go究竟是什么。

而Cameron Balahan这次的演讲算是Go团队加入Google Cloud后对Go未来定位和演进上的一次说明，虽然简短，但对Gopher们也极具参考意义。在这篇文章中，我们就来看看Cameron Balahan所代表的的Go团队对Go语言的观点。

Go是构建生产系统的高效平台

Go团队认为的第一点，也可能是最重要的一点是：Go不仅仅是一种编程语言，它是一个完整的端到端构建生产系统的平台。这一直都是Go团队的愿景。Go从一开始就是为了在规模化的实际软件工程中提供便利。并且，Go团队在Google内部将该愿景简化成了下面幻灯片中的使命陈述：Go提供了构建生产系统的最高效平台。

说Go很高效（Go is productive），是因为Go易于学习和维护，并且可以在团队之间扩展(scale)。

说Go是一个平台（Go is a platform），是因为它不仅仅是一种语言，它是一种端到端的开发者体验，包括IDE集成，构建和部署工具，监控工具，运行时工具，漏洞扫描等等，这些都是开箱即用的。

说Go是生产就绪的（Go is production ready ），是因为它可靠(reliable)、高效(efficient)、稳定(stable)和安全(secure)，这就是为什么大家会在企业中看到它的身影的原因，尤其是在关键业务系统和基础设施中，遍布整个云计算领域。实际上，这也是现代云计算本身建立在Go之上的原因。这并不仅仅指Google Cloud，我指的是所有主要的云服务提供商以及所有其他主要的参与者以及云工具和技术。

Go的无限双循环

无限双循环是一个很好的思考更广泛的软件开发生命周期的方式。左边的循环是内部开发循环，也就是大家编写代码的地方。你迭代地很快，寻求快速反馈和高效率。而右边的循环可以看作是外部循环，你已经部署了你的代码到生产中，你要监控和操作它。

因此，当Go团队将Go作为一个平台来考虑时，他们将考虑如何端到端地解决这整个过程，包括内部和外部循环。Cameron下面基于这个循环从developer velocity(开发人员效率)、security(安全)和performance(性能)等方面分别举一些Go如何解决这些问题的例子。

developer velocity(开发人员效率)

Go有一些旨在为了最大化你团队的开发人员效率的语言特性、工具和库。包括了从编写代码到将其推送到生产，再到之后可靠运维的整个过程。

Go团队提供IDE集成，包括为Visual Studio Code开发的插件，使其能够轻松利用其余工具链的特性。Go还提供了强大的并发模型，通过Goroutine实现。Go有内置的格式化工具、内置的测试框架和内置的调试器。Go编译器本身构建静态独立二进制文件，不依赖任何系统范围的依赖项或单独的运行时，这使得部署比其他语言更容易、更安全、更快。这是一种端到端的解决方案，用于获取和维护开发人员效率。

security(安全)

Go在安全性方面是领先者，这一点Go也是端到端解决的。如果你在关注最新的XZ软件供应链攻击新闻，你就会知道这是多么重要，也许比以往任何时候都更重要。这是Go团队非常重视的一个领域，因为他们已经看到在其他语言生态系统中，当一个流行的依赖项被破坏时会发生什么。

由于Go被用于云中所有这些关键基础设施，Go团队认识到安全性是Go应该提供的最重要的功能之一。从依赖管理系统开始，Go先后有了Go Module Mirror、Checksum Database和pkg.go.dev网站，它们都会警告你所依赖的库是否被篡改或遭受已知漏洞。

此外，Go的IDE集成很深入。如果你使用Go的VS Code插件，你会在IDE中就收到关于依赖项中的漏洞警告，包括你是否实际上从代码中调用了这些漏洞。这样，在真正依赖它们进入生产环境之前，你就知道了依赖项的安全态势。Go也是唯一一种将模糊测试内置并集成到其工具链中的主流语言。模糊测试就像一种自动化的测试类型，它会智能地操纵你程序的输入，以找出bug和漏洞。

最后，Go有兼容性承诺，从Go 1.0开始就确保没有破坏性更改。这意味着升级很容易，这使保持最新的安全修复变得容易，跟上增强功能也很容易。去年在Go 1.21中，Go团队在此基础上增加了向前和向后兼容性特性。Go团队确实将兼容性视为不仅仅是一种便利，更是一种关键的安全特性。

performance(性能)

Go的标准库功能丰富且健壮，并针对性能进行了优化。你可以真正构建任何东西，而无需导入一些重型库或框架。Go还有一个自我调优的垃圾收集器。如果你曾经花时间为Java调优垃圾收集器，你就会知道这简直就像是一份全职工作。它可能需要耗费的时间和你最初编写代码一样长。在Go中，垃圾收集器开箱即用，运行高效，并会自动调整以适应你的工作负载需求。 当然，还有Profile Guided Optimization(PGO)，使用过PGO的开发者都很喜欢它。有些开发者甚至已经看到了令人印象深刻的性能提升。

开箱即用(out of the box)

图片中所有这些特性都符合开箱即用的端到端解决方案这一框架，正是这使Go成为构建生产系统最高效的平台。

Go团队在做所有这些的同时，也获得了来自用户的非常出色的反馈。大部分Go用户真的很喜欢Go。我们在调查中一直看到这一点，客户满意度水平（93%）实际上在业内是罕见的。

Go特性与客户价值定位

第一行可视为与生产力相关的内容。Go支持快速入门、快速迭代、快速构建真正可扩展的生产应用程序。所有这些都转化为你更快获得价值。

第二行是关于可靠性的，包括安全性、兼容性以及所有能够减少你长期维护和运维负担的内容。负担越小，你的总体拥有成本就越低，你就有更多时间和资源专注于推动业务增长的新事物。

第三行是关于云的。Go就像是为云量身定制的一样。Go启用的库、集成和架构都是为云而设计的，而不是后来才重新调整以适应云。因此，你将比使用其他语言时能更快更轻松地实现云的优势。

最后，Go用户是快乐的。他们无论在哪里都很开心。而且在Google Cloud上，他们尤其开心。每个人都喜欢开心的开发人员和运维人员。

小结

Google I/O 2024大会上Go团队代表对Go语言及其在软件工程领域的定位做了新的诠释：Go不仅是一种编程语言，更是一个端到端构建生产系统的高效平台。

Go团队认为Go易学易维护，可扩展，同时可靠、高效、稳定和安全，适合在企业中使用，尤其是关键业务系统和基础设施领域。

文中介绍了将Go的愿景拆解为Go的”无限双循环”的理念。其中内循环侧重开发效率，外循环侧重可靠运维。Go在开发人员效率、安全性和性能等方面都有出色的解决方案。如IDE集成、并发模型、格式化工具、测试框架、调试器、静态部署等有助提高开发效率；依赖管理、漏洞扫描、模糊测试等确保安全性；垃圾回收、编译优化等提升性能。

此外，Go兼具快速入门、快速迭代、可扩展构建、安全可靠、低运维成本、云原生设计等特性，能让客户快速获得价值、降低总拥有成本、享受云优势，获得高客户满意度。Go可视为构建现代云基础设施的理想语言。

Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时，我们也会加强代码质量和最佳实践的分享，包括如何编写简洁、可读、可测试的Go代码。此外，我们还会加强星友之间的交流和互动。欢迎大家踊跃提问，分享心得，讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落，享受coding的快乐! 欢迎大家踊跃加入！

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。