Conventional Commits

约定式提交规范

约定式提交（Conventional Commits）是一种结构化的 Git 提交信息规范。它通过固定格式描述一次提交的类型、影响范围和具体变更，让提交历史更容易阅读、检索和自动化处理。

基本格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

常用写法：

feat(auth): add password reset flow
fix(api): handle empty response body
docs: update deployment guide

提交类型

Type	用途	示例
feat	新功能	feat(auth): add OAuth login
fix	Bug 修复	fix(form): prevent duplicate submit
docs	文档修改	docs: update API examples
style	代码格式或样式调整，不改变逻辑	style: format markdown files
refactor	重构代码，不新增功能也不修复 bug	refactor(user): split profile service
perf	性能优化	perf(list): reduce unnecessary renders
test	新增或修改测试	test(auth): add login failure cases
build	构建系统或依赖变更	build: upgrade astro
ci	CI 配置或脚本变更	ci: add build workflow
chore	杂项维护	chore: clean unused scripts
revert	回滚提交	revert: revert auth redirect change

Scope 怎么写

scope 用来说明这次提交影响的模块或范围，可选但推荐在中大型项目中使用。

<type>(<scope>): <description>

常见 scope 示例：

Scope	适用场景
auth	登录、注册、权限、令牌
api	接口、请求、响应处理
ui	通用界面、组件、样式
docs	文档站、笔记内容
config	配置文件、环境配置
deps	依赖升级或锁文件变更

示例：

feat(auth): add GitHub login
fix(ui): align dialog footer buttons
docs(git): improve commit convention notes
chore(deps): update eslint packages

描述怎么写

提交描述建议使用现在时、祈使句，并保持简短清晰。

推荐：

fix(api): handle missing user id
docs: add skill usage notes
refactor(auth): extract token helpers

不推荐：

fixed api bug
update
修改了一些东西

写描述时可以遵守这几条规则：

• 用一句话说明这次提交做了什么。
• 描述控制在 72 个字符以内。
• 使用动词开头，例如 add、fix、update、remove、extract。
• 不要把多个无关变更塞进同一个提交。

Body 和 Footer

当一行描述不足以解释变更原因时，可以添加正文。

refactor(auth): extract token refresh logic

Move refresh handling into a shared helper so route handlers and middleware
can reuse the same expiration and retry behavior.

Footer 常用于关联 issue 或声明破坏性变更。

fix(payment): handle cancelled checkout session

Closes #123

破坏性变更

如果这次提交会破坏已有 API、配置、数据结构或调用方式，需要明确标记。

方式一：在 type 或 scope 后添加 !。

feat!: remove legacy auth endpoint
feat(api)!: change profile response shape

方式二：在 footer 中添加 BREAKING CHANGE。

feat(config): support nested app config

BREAKING CHANGE: `config.theme` is now moved to `config.ui.theme`.

提交流程

1. 查看当前变更

先确认工作区有哪些文件被修改。

git status --porcelain

如果已经暂存了文件，优先查看暂存区 diff：

git diff --staged

如果还没有暂存文件，查看工作区 diff：

git diff

2. 按逻辑分组暂存

一次提交最好只包含一个逻辑变更。不要把功能、格式化、文档、依赖升级混在一起。

git add src/content/docs/git/commits.md

需要精细拆分时可以使用交互式暂存：

git add -p

3. 根据 diff 生成提交信息

根据实际变更判断：

• type：这是什么类型的变更？
• scope：影响哪个模块？
• description：一句话描述做了什么？

例如只修改文档笔记：

docs(git): improve conventional commits notes

例如修复登录逻辑：

fix(auth): handle expired refresh token

4. 执行提交

单行提交：

git commit -m "docs(git): improve conventional commits notes"

需要正文时：

git commit -m "refactor(auth): extract token refresh logic" -m "Move refresh handling into a shared helper for middleware and route handlers."

安全注意事项

提交前需要确认没有把敏感信息加入版本库。

不要提交：

• .env
• 私钥文件
• 访问令牌
• 数据库密码
• 生产环境配置
• 包含真实用户数据的文件

同时避免随意执行破坏性 Git 操作，例如：

git reset --hard
git push --force

这类命令会改写或丢弃历史，只有在明确知道后果并确认需要时才使用。

常用速查

变更内容	推荐提交信息
新增功能	feat(scope): add something
修复问题	fix(scope): handle something
修改文档	docs(scope): update something
调整格式	style(scope): format something
重构代码	refactor(scope): extract something
优化性能	perf(scope): improve something
添加测试	test(scope): add something cases
更新依赖	build(deps): update package name
修改 CI	ci: update workflow
杂项维护	chore: clean something