Github代码提交信息规范

为提升代码提交信息的可读性和维护性，推荐遵循以下规范。本规范扩展了常用提交类型，并细化了格式要求，支持自动化生成变更日志（CHANGELOG）和版本管理。

## 提交类型分类

### 主要类型（影响版本功能）

| 类型     | 说明                                         |
| -------- | -------------------------------------------- |
| `feat` | 新增功能（feature），通常对应 Minor 版本更新 |
| `fix`  | Bug 修复，通常对应 Patch 版本更新            |

### 特殊类型（非功能代码变更）

| 类型         | 说明                                            |
| ------------ | ----------------------------------------------- |
| `docs`     | 仅文档更新（如 README、CHANGELOG、注释等）      |
| `style`    | 代码格式调整（空格、缩进、分号等），不改变逻辑  |
| `refactor` | 代码重构，既非新增功能也非修复 Bug              |
| `test`     | 测试用例新增或修改（包括单元测试、集成测试）    |
| `chore`    | 非代码/文档的杂项变更（如构建脚本、工具配置等） |

### 扩充类型（扩展场景支持）

| 类型         | 说明                                                     |
| ------------ | -------------------------------------------------------- |
| `build`    | 构建系统或外部依赖变更（如 webpack、npm、Gradle）        |
| `perf`     | 性能优化相关的代码变更                                   |
| `ci`       | CI 配置或脚本修改（如 GitHub Actions、Jenkins、Travis）  |
| `revert`   | 回滚某次提交                                             |
| `security` | 安全补丁或防护措施（如 XSS、SQL 注入修复）               |
| `db`       | 数据库相关变更（迁移脚本、表结构修改）                   |
| `i18n`     | 国际化或本地化调整（如多语言文案、时区处理）             |
| `typo`     | 修复代码或文档中的拼写错误（若影响功能，优先用 `fix`） |

## 提交信息格式规范

### 基础格式

```plaintext
<类型>[可选范围]: <描述>  -- 标题行（必填）
// 空一行
[可选正文]  -- 正文（可选）
// 空一行
[可选页脚]  -- 页脚（可选）
```

#### 格式说明

1. **标题行（必填）**
   * **类型**：从上述分类中选择，使用英文小写。
   * **范围（可选）**：用括号包裹，描述影响模块（如 `(auth)`, `(user-api)`）。
   * **描述**：简明扼要，使用**现在时**（如 "add" 而非 "added"），**首字母小写**，**无句号结尾**。
2. **正文（可选）**
   * 详细描述变更内容、动机及与之前行为的对比。
   * 使用祈使句（如 "Change default timeout to..."）。
3. **页脚（可选）**
   * **关联 Issue**：如 `Closes #123`, `Related #45`。
   * **破坏性变更**：以 `BREAKING CHANGE:` 开头，说明变动及迁移方式。

#### 示例

```plaintext
feat(user): 新增邮箱绑定功能 (#42)

- 添加邮箱验证接口 POST /verify-email
- 实现绑定成功后的邮件通知服务
- 增加用户设置页面的邮箱管理UI组件
```

```plaintext
fix(auth): 修复JWT令牌过期时间计算错误

- 将时间单位从秒修正为毫秒
- 增加token有效期测试用例
- 修复相关文档中的错误描述
```

```plaintext
docs(README): 添加项目本地启动指南

- 补充Node.js版本要求说明
- 增加环境变量配置示例
- 附调试模式启动命令
```

```plaintext
refactor(payment): 解耦支付回调处理逻辑

- 抽离支付宝/微信支付解析器
- 引入策略模式实现支付网关
- 保持原有接口兼容性
```

```plaintext
perf(db): 优化用户查询SQL性能

- 为user_id添加复合索引
- 重写N+1查询为JOIN语句
- 查询响应时间从1200ms降至150ms
```

```plaintext
test(calculator): 增加税率计算边界测试

- 添加零值/负值输入测试
- 覆盖税率阶梯临界点用例
- 修复浮点数精度问题
```

```plaintext
style(profile): 优化移动端头像上传交互

- 增加拖拽上传区域视觉反馈
- 裁剪控件添加手势缩放支持
- 统一错误提示Toast样式
```

```plaintext
chore(deps): 升级axios到v1.6.0

- 修复CVE-2023-45857漏洞
- 更新拦截器类型定义
- 移除已弃用的maxContentLength配置
```

```plaintext
hotfix(order): 修复支付成功状态未更新

- 修复MQ消息丢失导致的回调失败
- 增加支付状态补偿机制
- 紧急补丁版本v1.2.1
```

```plaintext
WIP(search): 实现商品搜索分词功能

- 集成jieba中文分词库
- 构建商品关键词倒排索引
- TODO: 优化长尾词匹配算法
```

```plaintext
BREAKING CHANGE(api): 重构用户端点路径

- /api/v1/users => /api/core/users
- 移除旧版地址支持
- 升级指南见 MIGRATION.md
```

```plaintext
i18n(login): 新增法语语言包

- 翻译登录页全部文案
- 添加语言切换下拉菜单
- 支持动态加载语言资源
```

```plaintext
config(ci): 迁移到GitHub Actions

- 添加单元测试流水线
- 配置自动部署到Staging环境
- 移除Travis CI配置文件
```

```plaintext
build: 添加Docker多阶段构建

- 优化生产环境镜像大小
- 分离构建依赖与运行环境
- 镜像体积从1.2GB降至280MB
```

```plaintext
release: v2.3.0 电商大促版本

- 支持限时秒杀功能
- 新增拼团模块
- 优化库存扣减性能
```

## 高级规范

### 长度限制

* **标题行**：不超过 50 个字符
* **正文每行**：不超过 72 个字符（避免 GitHub 自动换行）

### 语言与符号

* 使用英文（开源项目推荐）或团队统一语言
* 避免 Emoji 或特殊符号（可结合 Gitmoji 扩展，但需团队统一）

### 范围（Scope）推荐

| 范围示例   | 适用场景     |
| ---------- | ------------ |
| `(auth)` | 认证模块     |
| `(db)`   | 数据库相关   |
| `(ci)`   | 持续集成流程 |
| `(ui)`   | 用户界面组件 |

## 常见问题

### 如何选择类型？

* 影响用户的新功能 → `feat`
* 修复用户可感知的缺陷 → `fix`
* 仅开发者相关的变动 → `chore` 或 `build`

### 多类型变更如何处理？

### 原则

1. **主次分明**：选择**最主要**的变更类型作为标题类型
2. **补充说明**：在正文中描述次要变更，用  `(fixes #issue)` 等标记关联问题
3. **保持原子性**：如涉及不相关的大改动，应拆分为多个提交

**示例**：重构代码时修复了Bug

```plaintext
refactor(auth): 简化令牌验证逻辑

- 移除冗余的加密步骤
- 修复token过期检查问题 (fixes #89)
```

AI摘要

本文介绍了一种代码提交信息规范，旨在提高代码的可读性和维护性。规范包括提交类型的分类（主要类型、特殊类型和扩充类型），提交信息的格式规范（基础格式、格式说明和示例），以及高级规范（长度限制、语言与符号、范围推荐）。此外，还提供了常见问题的解答，帮助开发者更好地遵循规范。

提交类型分类

主要类型（影响版本功能）

类型	说明
`feat`	新增功能（feature），通常对应 Minor 版本更新
`fix`	Bug 修复，通常对应 Patch 版本更新

特殊类型（非功能代码变更）

类型	说明
`docs`	仅文档更新（如 README、CHANGELOG、注释等）
`style`	代码格式调整（空格、缩进、分号等），不改变逻辑
`refactor`	代码重构，既非新增功能也非修复 Bug
`test`	测试用例新增或修改（包括单元测试、集成测试）
`chore`	非代码/文档的杂项变更（如构建脚本、工具配置等）

扩充类型（扩展场景支持）

类型	说明
`build`	构建系统或外部依赖变更（如 webpack、npm、Gradle）
`perf`	性能优化相关的代码变更
`ci`	CI 配置或脚本修改（如 GitHub Actions、Jenkins、Travis）
`revert`	回滚某次提交
`security`	安全补丁或防护措施（如 XSS、SQL 注入修复）
`db`	数据库相关变更（迁移脚本、表结构修改）
`i18n`	国际化或本地化调整（如多语言文案、时区处理）
`typo`	修复代码或文档中的拼写错误（若影响功能，优先用 `fix`）

提交信息格式规范

基础格式

<类型>[可选范围]: <描述>  -- 标题行（必填）
// 空一行
[可选正文]  -- 正文（可选）
// 空一行
[可选页脚]  -- 页脚（可选）

格式说明

标题行（必填）
- 类型：从上述分类中选择，使用英文小写。
- 范围（可选）：用括号包裹，描述影响模块（如 (auth), (user-api)）。
- 描述：简明扼要，使用现在时（如 "add" 而非 "added"），首字母小写，无句号结尾。
正文（可选）
- 详细描述变更内容、动机及与之前行为的对比。
- 使用祈使句（如 "Change default timeout to..."）。
页脚（可选）
- 关联 Issue：如 Closes #123, Related #45。
- 破坏性变更：以 BREAKING CHANGE: 开头，说明变动及迁移方式。

示例

feat(user): 新增邮箱绑定功能 (#42)

- 添加邮箱验证接口 POST /verify-email
- 实现绑定成功后的邮件通知服务
- 增加用户设置页面的邮箱管理UI组件

fix(auth): 修复JWT令牌过期时间计算错误

- 将时间单位从秒修正为毫秒
- 增加token有效期测试用例
- 修复相关文档中的错误描述

docs(README): 添加项目本地启动指南

- 补充Node.js版本要求说明
- 增加环境变量配置示例
- 附调试模式启动命令

refactor(payment): 解耦支付回调处理逻辑

- 抽离支付宝/微信支付解析器
- 引入策略模式实现支付网关
- 保持原有接口兼容性

perf(db): 优化用户查询SQL性能

- 为user_id添加复合索引
- 重写N+1查询为JOIN语句
- 查询响应时间从1200ms降至150ms

test(calculator): 增加税率计算边界测试

- 添加零值/负值输入测试
- 覆盖税率阶梯临界点用例
- 修复浮点数精度问题

style(profile): 优化移动端头像上传交互

- 增加拖拽上传区域视觉反馈
- 裁剪控件添加手势缩放支持
- 统一错误提示Toast样式

chore(deps): 升级axios到v1.6.0

- 修复CVE-2023-45857漏洞
- 更新拦截器类型定义
- 移除已弃用的maxContentLength配置

hotfix(order): 修复支付成功状态未更新

- 修复MQ消息丢失导致的回调失败
- 增加支付状态补偿机制
- 紧急补丁版本v1.2.1

WIP(search): 实现商品搜索分词功能

- 集成jieba中文分词库
- 构建商品关键词倒排索引
- TODO: 优化长尾词匹配算法

BREAKING CHANGE(api): 重构用户端点路径

- /api/v1/users => /api/core/users
- 移除旧版地址支持
- 升级指南见 MIGRATION.md

i18n(login): 新增法语语言包

- 翻译登录页全部文案
- 添加语言切换下拉菜单
- 支持动态加载语言资源

config(ci): 迁移到GitHub Actions

- 添加单元测试流水线
- 配置自动部署到Staging环境
- 移除Travis CI配置文件

build: 添加Docker多阶段构建

- 优化生产环境镜像大小
- 分离构建依赖与运行环境
- 镜像体积从1.2GB降至280MB

release: v2.3.0 电商大促版本

- 支持限时秒杀功能
- 新增拼团模块
- 优化库存扣减性能

高级规范

长度限制

标题行：不超过 50 个字符
正文每行：不超过 72 个字符（避免 GitHub 自动换行）

语言与符号

使用英文（开源项目推荐）或团队统一语言
避免 Emoji 或特殊符号（可结合 Gitmoji 扩展，但需团队统一）

范围（Scope）推荐

范围示例	适用场景
`(auth)`	认证模块
`(db)`	数据库相关
`(ci)`	持续集成流程
`(ui)`	用户界面组件

常见问题

如何选择类型？

影响用户的新功能 → feat
修复用户可感知的缺陷 → fix
仅开发者相关的变动 → chore 或 build

多类型变更如何处理？

原则

主次分明：选择最主要的变更类型作为标题类型
补充说明：在正文中描述次要变更，用 (fixes #issue) 等标记关联问题
保持原子性：如涉及不相关的大改动，应拆分为多个提交

示例：重构代码时修复了Bug

refactor(auth): 简化令牌验证逻辑

- 移除冗余的加密步骤
- 修复token过期检查问题 (fixes #89)

最后修改：2025 年 09 月 26 日

如果觉得我的文章对你有用，请随意赞赏

Github代码提交信息规范

提交类型分类

主要类型（影响版本功能）

特殊类型（非功能代码变更）

扩充类型（扩展场景支持）

提交信息格式规范

基础格式

格式说明

示例

高级规范

长度限制

语言与符号

范围（Scope）推荐

常见问题

如何选择类型？

多类型变更如何处理？

原则

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

1 条评论

原神启动器 - 帮助您快速开始一段游戏旅程！

为你的Handsome主题添加B站小黄脸表情包

FFmpeg的安装使用，以及m3u8切片方法

CSGO创建战队教程，创建战队的详细步骤来了！

为你的电脑添加初音未来鼠标指针

使用 KMS 激活 Microsoft 产品

「转载」又是一种 Minecraft 外置登录解决方案：自行实现 Yggdrasil API

将 Github 上的提交标记为 Verified

Github代码提交信息规范

2021年元旦福利活动

Github代码提交信息规范

提交类型分类

主要类型（影响版本功能）

特殊类型（非功能代码变更）

扩充类型（扩展场景支持）

提交信息格式规范

基础格式

格式说明

示例

高级规范

长度限制

语言与符号

范围（Scope）推荐

常见问题

如何选择类型？

多类型变更如何处理？

原则

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

1 条评论

Github代码提交信息规范

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款