118 lines
3.5 KiB
Markdown
118 lines
3.5 KiB
Markdown
|
||
|
||
[来源网站](https://www.conventionalcommits.org/zh-hant/v1.0.0/)
|
||
|
||
## 提交说明
|
||
|
||
### 基础结构
|
||
|
||
```
|
||
<type>[optional scope]: <description>
|
||
|
||
[optional body]
|
||
|
||
[optional footer(s)]
|
||
|
||
# 译文
|
||
|
||
<类型>[可选 范围]: <描述>
|
||
|
||
[可选 正文]
|
||
|
||
[可选 脚注]
|
||
```
|
||
|
||
### 类型（type）
|
||
|
||
- feat: 表示在代码库中新增了一个功能；
|
||
- fix: 表示在代码库中修复了一个 bug；
|
||
|
||
- build: 用于修改项目构建系统或外部依赖，例如升级依赖版本等；
|
||
- chore: 用于其他不修改`src`或`test`文件的杂项任务，例如更新`.gitignore`、修改编辑器配置等；
|
||
- ci: 用于修改持续集成/持续部署的配置与脚本，例如`GitHub Actions`、`Jenkins`、`Travis` 等工作流；
|
||
- docs: 用于修改文档，例如修改`README`文件、API文档等；
|
||
- style: 用于修改代码格式（不影响代码逻辑），例如调整缩进、空格、分号、引号风格等；
|
||
- refactor: 用于重构代码，例如修改代码结构、变量名、函数名等但不修改功能逻辑；
|
||
- improvement: 用于对现有实现进行改进，例如优化算法、增强健壮性等（不涉及新功能或 bug 修复）；
|
||
- revert: 用于回退之前的提交，描述应使用被回退提交的标题，并在脚注中用 `Refs:` 引用被回退的 commit SHA；
|
||
- perf: 用于优化性能，例如提升代码的性能、减少内存占用等；
|
||
- wip: 用于保存尚未完成的工作进度（Work In Progress）；
|
||
- test: 用于修改测试用例，例如添加、删除、修改代码的测试用例等；
|
||
|
||
> 破坏性变更**必须**在提交信息中标记出来，有两种方式：
|
||
>
|
||
> 1.在 `<类型>[可选 范围]` 后、冒号前添加 `!`，例如：`feat!: ...` 或 `refactor(api)!: ...`
|
||
>
|
||
> 2.*在脚注中添加* `BREAKING CHANGE: <描述>`
|
||
>
|
||
> 这两种方式可以同时使用，也可以只用其一。
|
||
|
||
### 范围（Scope）
|
||
|
||
范围用于标识本次修改影响的模块或组件，例如：
|
||
|
||
- feat(auth): ... （auth 模块）
|
||
|
||
- fix(parser): ... （parser 模块）
|
||
|
||
- build(deps): ... （依赖管理）
|
||
|
||
范围名称建议使用小写英文，多个单词用 `-` 连接，例如 `user-profile`。
|
||
|
||
### 描述（description）
|
||
|
||
描述用于简要概括本次变更的内容，要求：
|
||
|
||
- 使用祈使语气、现在时态（例如用 "add" 而非 "added" 或 "adds"）；
|
||
|
||
- 小写开头，末尾不加句号；
|
||
|
||
- 长度建议控制在50个字符以内（中文约 25 个字）;
|
||
|
||
### 正文（Body）
|
||
|
||
正文是可选的，用于对本次变更进行更详细的说明，包括：
|
||
|
||
- 变更的动机（为什么这样做）
|
||
|
||
- 与之前行为的对比
|
||
|
||
- 实现方案的简要说明
|
||
|
||
正文与描述之间**必须**空一行，正文内部段落之间也可以空行分隔。
|
||
|
||
### 脚注（Footer）
|
||
|
||
脚注用于记录元信息，常见用法：
|
||
|
||
- `BREAKING CHANGE: <描述>` — 标记破坏性变更;
|
||
|
||
- `Closes #123` 或 `Fixes #456` — 关联 Issue/PR;
|
||
|
||
- `Refs: abc123` — 引用相关提交;
|
||
|
||
- `Reviewed-by: <name>` — 标记审查者;
|
||
|
||
- `Co-authored-by: <name> <email>` — 标记共同作者;
|
||
|
||
## 示例
|
||
|
||
### 基础功能提交
|
||
feat(auth): add JWT token refresh mechanism
|
||
|
||
### Bug 修复（含关联 issue）
|
||
fix(parser): handle empty string input edge case
|
||
|
||
Closes #123
|
||
|
||
### 破坏性变更（使用 ! 前缀）
|
||
feat(api)!: change user endpoint response format
|
||
|
||
BREAKING CHANGE: the `GET /api/users` endpoint now returns
|
||
a paginated response instead of a flat array.
|
||
|
||
### 回退提交
|
||
revert: remove experimental cache layer
|
||
|
||
Refs: a1b2c3d
|