Summary: Conventional Commits 是一种广泛使用的提交消息规范, 旨在通过标准化的格式提高提交信息的可读性、可维护性, 并支持自动化工具 (如生成 CHANGELOG、语义化版本控制等).
本文由 deepseek-r1 辅助生成.
Conventional Commits 核心格式
提交消息的格式为:
1
2
3
| <type>[optional scope]: <subject>
[optional body]
[optional footer]
|
1. 类型 (Type)
| 类型 | 说明 |
|---|
feat | 新增功能 (对应语义化版本的 minor) |
fix | 修复 Bug (对应语义化版本的 patch) |
docs | 文档更新 (如 README、注释等) |
style | 代码样式调整 (不影响逻辑的格式修改, 如空格、缩进等) |
refactor | 代码重构 (既不修复 Bug 也不新增功能的结构性修改) |
perf | 性能优化 |
test | 测试代码更新 (单元测试、集成测试等) |
build | 构建工具或依赖更新 (如 Webpack、npm 等) |
ci | CI 配置修改 (如 GitHub Actions、Travis 等) |
chore | 其他杂项修改 (不涉及代码或文档的改动, 如清理临时文件) |
revert | 回滚之前的提交 |
2. 作用域 (Scope, 可选)
- 描述修改的影响范围 (如模块、组件、文件等), 用括号包裹:
1
2
| feat(login): add OAuth2 support
fix(api): handle null response
|
3. 主题 (Subject)
- 简短描述 (不超过 50 字符), 使用祈使语气 (如 “add” 而非 “added”):
1
| docs: update installation guide
|
4. 正文 (Body, 可选)
1
2
3
4
| fix: prevent memory leak in data processing
- Add cleanup logic for event listeners
- Update error handling in async functions
|
- 关联 Issue: 关闭的问题或任务 (如
Closes #123) - 破坏性变更: 用
BREAKING CHANGE: 标记重大变更 (触发语义化版本的 major 版本) :
1
2
3
| feat: remove deprecated API
BREAKING CHANGE: The `oldMethod()` is no longer supported.
|
完整示例
1
2
3
4
5
6
7
| feat(auth): add password reset endpoint
- Add POST /auth/reset-password endpoint
- Send email notification on reset request
Closes #45
BREAKING CHANGE: Remove deprecated `resetByUsername` method
|
扩展规范 (Angular 风格)
许多团队基于 Angular Commit Guidelines 扩展, 例如:
ci: 持续集成配置build: 构建系统perf: 性能优化revert: 回滚提交
自定义规范 (服务于博客)
在个人博客场景中, 大部分提交可能确实围绕内容创作和文档维护展开. 如果觉得 docs 类型过于笼统, 可以基于 Conventional Commits 的灵活性和你的实际需求, 自定义更细分的类型. 以下是一些针对博客优化的类型建议:
自定义类型建议
| 类型 | 适用场景 |
|---|
post | 发布新文章 (替代 feat, 专用于内容创作) |
update | 更新已有文章 (如补充段落、修正过时信息) |
meta | 元数据修改 (如调整文章分类、标签、SEO关键词等) |
seo | SEO 优化 (如添加 Alt 文本、优化标题、调整 sitemap) |
media | 媒体文件更新 (新增/替换图片、视频、音频等) |
fix | 修正错误 (如文章中的技术错误、死链修复等) |
style | 排版或样式调整 (如 Markdown 格式、代码高亮、CSS 美化) |
translate | 翻译内容 (新增或更新多语言版本) |
refactor | 内容重构 (重新组织文章结构, 优化逻辑流) |
chore | 维护性任务 (如更新依赖、清理冗余文件) |
使用示例
1. 发布新文章
1
| post: add article about quantum computing basics
|
或带作用域 (如分类):
1
| post(physics): introduce quantum entanglement
|
2. 更新现有文章
1
| update: add code example to CSS animation guide
|
3. 调整标签/分类
1
| meta: add 'AI' tag to GPT-4 article
|
4. SEO 优化
1
| seo: optimize meta description for homepage
|
5. 媒体文件管理
1
| media: replace header image with WebP format
|
扩展建议
保持类型简洁:
避免过度细分 (如 image/video 可统一为 media), 否则会增加维护成本.
结合作用域 (Scope):
用作用域标记文章分类、技术栈等, 增强可读性:
1
2
| update(react): migrate class component to hooks
fix(linux): correct permission command in tutorial
|
在 README 中记录规范:
在博客仓库的文档中明确自定义类型, 便于协作 (示例) :
1
2
3
4
5
6
| ## 提交规范
- `post`: 新文章
- `update`: 更新旧文
- `meta`: 标签/分类调整
- `seo`: 搜索引擎优化
...
|
与标准 Conventional Commits 的对比
| 标准类型 | 博客场景替代类型 | 优势 |
|---|
docs | post, update | 明确区分新内容创作与旧内容更新 |
feat | post | 避免将文章发布与技术功能新增混用 |
style | style | 保留, 用于代码或排版美化 |
chore | chore | 保留, 用于维护任务 |
何时仍应使用 docs？
如果博客包含非文章类文档 (如项目说明、API 文档) , 可保留 docs 类型:
1
| docs: update contribution guidelines
|
使用 emoji
在 commit 消息前加入 emoji 可能会帮助你更快的了解信息.
vscode 插件.
References