约定式提交：从规范语法到自动化交付

1. 规范概述与背景起源

---

2. 为什么业界更青睐约定式提交：核心价值与工程实践

2.1 降低代码审查（Code Review）中的认知负荷

场景对比

• 非规范提交方式：

  commit abc1234: optimize user query logic

  该信息存在语义歧义：优化是仅改变了内部性能，还是顺带重构了异常处理？亦或变更了返回字段？审查者必须通读所有代码及调用方上下文，以排查潜在的非向后兼容风险。

• 约定式提交方式：

  refactor(user): simplify SQL joins in user query

  或者：

  perf(user): cache query results to reduce DB latency

2.2 提升缺陷溯源与代码检索效率

结构化检索示例

# 精确筛选近两周合并进主分支的所有新功能（feat）提交
git log --grep="^feat" --oneline --since="2 weeks ago"

# 快速过滤出针对权限模块（auth）的所有缺陷修复
git log --grep="^fix(auth)" --oneline

与 git bisect 的协同效应

2.3 将发布流程转化为确定性状态机

1. 负责人人工查阅两次 Git Tag 之间的变更列表。
2. 人工辨别哪些变动属于新特性、缺陷修复或构建脚本调整。
3. 手动排版编写 CHANGELOG.md。
4. 凭经验主观决定应该递增主版本号、次版本号还是修订号。

[Git Commit History]
        │
        ▼ (抽象语法树 AST 解析)
[语义化版本分析器]
   ├── 检测到 BREAKING CHANGE ──> 触发 MAJOR 升级 (x.0.0)
   ├── 检测到 feat 提交       ──> 触发 MINOR 升级 (0.x.0)
   └── 检测到 fix 提交        ──> 触发 PATCH 升级 (0.0.x)
        │
        ▼ (自动化执行)
1. 提取所有提交，自动分类生成 CHANGELOG.md
2. 更新工程元数据（如 package.json）中的版本号
3. 自动生成 Git Tag 并完成构建制品的打包发布

---

3. 形式化语法定义

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

3.1 首行组成（Header）

1. Type（类型，必须）：
   • 必须为小写名词，明确代码变动的技术属性（如 feat、fix）。
2. Scope（影响范围，可选）：
   • 位于 Type 之后，由英文小括号包裹，用于限定变更的代码库边界（例如：feat(api): ...）。
3. 分隔符（必须）：
   • Type（或闭合的小括号）之后必须紧跟一个英文半角冒号 : 与一个半角空格。
4. Description（描述，必须）：
   • 紧随冒号与空格之后，提供简明扼要的代码变动总结。
   • 必须使用祈使语气和现在时态（例如使用 add 而非 added 或 adds）。
   • 首字母推荐小写，结尾不得添加句号。

3.2 正文（Body，可选）

• 位于 Header 之后，两者之间必须保留至少一行空行。
• 用于展开说明本次修改的设计考量、替代方案选择以及改动的原因（Why），而非重述代码细节。
• 正文支持多段落，段落间同样以空行分隔。

3.3 页脚（Footer，可选）

• 位于 Body（若无 Body 则位于 Header）之后，之间必须保留至少一行空行。
• 遵循特定键值格式：<token>: <value> 或 <token> #<value>。其中 Token 必须使用破折号连接或全大写字符（如 Refs: #123、Co-authored-by: user <user@example.com>，参考 Git Trailers 规范）。
• 用于标记问题追踪系统编号或破坏性变更。

3.4 破坏性变更（Breaking Change）语法规则

1. 感叹号标记法（推荐）：在 Header 的 Type/Scope 之后、冒号之前添加感叹号 !：

   feat(runtime)!: drop support for Node.js 16

2. Footer 标记法：在 Footer 的 Token 中使用 BREAKING CHANGE:：

   refactor: simplify authentication interface
   
   BREAKING CHANGE: The `loginWithCredentials` method now expects an object instead of positional parameters.

---

4. 与语义化版本（SemVer 2.0.0）的映射逻辑

提交特征	含义解释	对应 SemVer 递增维度	版本演进示例
fix	缺陷修复（保持向后兼容）	PATCH（修订号）	1.0.0 ➡️ 1.0.1
feat	新增功能（保持向后兼容）	MINOR（次版本号）	1.0.0 ➡️ 1.1.0
! 或 BREAKING CHANGE	破坏向后兼容性的任何类型修改	MAJOR（主版本号）	1.0.0 ➡️ 2.0.0

---

5. 常用 Type 的语义边界界定

• feat（Feature）：引入新功能、新增接口参数或新增公开能力。
• fix（Bug Fix）：修复已知缺陷、纠正逻辑漏洞或恢复异常行为。
• docs（Documentation）：仅涉及文档、注释或说明文件的修改，不包含任何业务与构建代码的变更。
• style（Code Style）：不影响代码运行逻辑的纯格式变更（如调整缩进、清除行末空格、调整导入顺序等，通常由代码格式化器如 Prettier 生成）。

  边界警示：前端界面 CSS 视觉样式的修改不属于此类别。界面布局变更新增功能属于 feat，修复渲染错位属于 fix。

• refactor（Refactoring）：代码重构。既不增加功能，也不修复缺陷的代码结构性优化。
• perf（Performance）：专门旨在提升运行性能、减少内存消耗或降低网络延迟的优化变动。
• test（Testing）：添加缺失的测试用例、完善现有测试覆盖率或修正测试脚本。
• build（Build System）：影响构建系统、外部依赖包（如 package.json 中的依赖变动）或打包配置的变动。
• ci（Continuous Integration）：持续集成流水线配置与脚本的变更（如 GitHub Actions、GitLab CI/CD）。
• chore（Chores）：不属于上述任何类别的维护性日常事务。

---

6. 范例解析与常见错误纠正

6.1 符合规范的标准范例

• 标准功能开发（含 Scope）：

  feat(cache): implement redis cluster connection pooling

• 破坏性变更的重构提交：

  refactor(router)!: migrate routing engine to trie tree

• 完整多段落提交（含详细上下文与追踪系统关联）：

  fix(parser): prevent infinite loop on unclosed markdown blockquotes
  
  The parser entered an infinite loop when encountering an EOF immediately
  following an unclosed blockquote marker. Added boundary check before parsing lines.
  
  Closes #512

6.2 常见错误写法及技术分析

案例 1：缺少空格与时态错误

• 错误写法：

  fix:fixed the calculation bug.

• 问题分析：
  1. 冒号之后缺少半角空格。
  2. 使用了过去式 fixed 而非祈使句现在时 fix。
  3. 尾部包含了多余的句号。
• 纠正：

  fix(calculator): resolve floating point rounding error

案例 2：混淆 style 与视觉样式

• 错误写法：

  style(navbar): change background color to dark blue

• 问题分析：将界面的 UI 视觉改动错误标记为了 style。在规范中，style 仅指代代码排版风格。界面的功能性视觉调整属于新特性或修复。
• 纠正：

  feat(navbar): support dark mode theme styling

案例 3：混合提交（Non-atomic Commit）

• 错误写法：

  feat(user): add register page, fix login bug and update docs

• 问题分析：在一个提交中融合了新功能、Bug 修复和文档变更，破坏了提交的原子性，导致自动化分析工具无法准确定位版本号升级步长。
• 纠正：应拆分为三个独立的 Git Commit 分别提交：
  1. feat(user): add user registration page
  2. fix(auth): correct token validation logic on login
  3. docs(user): add api documentation for registration flow

---

7. 工程化落地与自动化工具链

7.1 本地静态校验：commitlint 与 husky

1. 安装工具链依赖：

   yarn add --dev @commitlint/cli @commitlint/config-conventional husky

2. 创建配置文件（commitlint.config.js）： 参考 commitlint 配置文档：

   module.exports = {
     extends: ['@commitlint/config-conventional'],
     rules: {
       'type-enum': [
         2,
         'always',
         [
           'feat',
           'fix',
           'docs',
           'style',
           'refactor',
           'perf',
           'test',
           'build',
           'ci',
           'chore'
         ]
       ],
       'subject-case': [2, 'never', ['upper-case']],
     },
   };

3. 配置 Git 钩子拦截（基于 Husky）：

   yarn husky install
   yarn husky add .husky/commit-msg 'yarn commitlint --edit "$1"'

7.2 变更日志生成与自动发布：semantic-release

1. 抽象语法树（AST）分析器扫描上一个 Git Tag 之后的新提交。
2. 依据 feat、fix、BREAKING CHANGE 推导出符合 SemVer 规则的新版本号。
3. 按照内置模版提取变更摘要，自动向 CHANGELOG.md 追加内容。
4. 打上对应的 Git Tag，并触发后续的打包构建与发布流水线（如推送到 npm 官方仓库 或 GitHub Releases）。

---

8. 规范核心速查表

Type	语义职责	英文对应分类
feat	引入新功能	Features
fix	修复软件缺陷	Bug Fixes
docs	仅修改文档说明	Documentation
style	代码格式、排版调整，不涉及代码逻辑	Code Formatting
refactor	代码重构，既不增新功能也不修缺陷	Refactoring
perf	提升运行效率或减少资源消耗的优化	Performance
test	增加或修改测试代码	Tests
build	构建配置、外部依赖项调整	Build & Dependencies
ci	持续集成流水线脚本与配置调整	CI/CD Configuration
chore	其他日常维护性事务	Maintenance

语法结构与变更标记

• 基础格式约束：

  <type>[optional scope]: <description>

• 破坏性变更声明：
  • 首行标记：<type>!: <description>
  • 页脚声明：在 Footer 声明 BREAKING CHANGE: <description>

---

9. 权威参考与一手资料出处

• Conventional Commits Specification (v1.0.0)
• Semantic Versioning 2.0.0 (SemVer Specification)
• RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
• Angular Commit Message Guidelines
• Git Documentation (git-scm.com/doc)
• Commitlint Documentation
• Semantic-release Documentation