docs: 明确 Git 提交信息与 PR 标题使用中文

原 GIT-05 要求 subject 用英文祈使句,与团队实际书写习惯不符(已有提交均为
中文),且缺少中英混排与术语约定,容易写出 Chinglish、自造术语或中英标点混乱。

本次改动:
- GIT-05 改为「提交信息一律使用中文」,type / scope 保留英文小写,规定祈使句、
  字数(≤50 汉字 / 整行 ≤72 字符)与不加句末标点;
- 新增 GIT-21~GIT-23:中英文间加空格、使用全角标点与反引号、术语沿用 PRD 术语表、
  禁止 Chinglish 与无信息缩写;
- 新增 §2.2 commitlint 配置要点:中文必须关闭 subject-case、拦截中文句号,
  否则钩子校验实际无效;
- 同步 03(commit-msg 钩子说明)、07(PR-01 标题用中文)与 AGENTS §7 / §9 / 附录。

影响面:仅文档,无代码影响。新规则对后续提交生效,已推送的历史提交不改写
(GIT-15 禁止改写 main 历史)。
回滚方式:git revert 本提交。
This commit is contained in:
Stev_Wang committed 2026-11-02 15:12:56 +08:00
1 parent c50ee7b57a
commit 75cedbe97b
5 files changed
+34 -10

No files matched your search

+28 -4
View File
@@ -34,9 +34,9 @@
## 2 提交信息(Conventional Commits 1.0)
```
<type>(<scope>): <subject>
<type>(<scope>): <中文简述>
<body:为什么改 + 影响面,中文>
<body:中文,说明为什么改 + 影响面 / 回滚方式>
<footer:BREAKING CHANGE / Refs: R-xx / Closes #12>
```
@@ -57,7 +57,7 @@
规则:
- `GIT-05` `subject` 用英文祈使句,≤ 72 字符,**不加句号**;中文放正文。
- `GIT-05` 提交信息(`subject` + 正文)**一律使用中文**;`type` / `scope` 保留英文小写。`subject` 用祈使句(「新增 …」而非「新增了 …」「新增的 …」),≤ 50 个汉字且整行 ≤ 72 字符,**不加句末标点**(英文 `.` 与中文 `。` 均禁止)。
- `GIT-06` `scope` 必填,取值见 `GIT-01`。
- `GIT-07` 正文说明「**为什么**」与「**影响面 / 回滚方式**」;纯重命名类可仅一行 subject。
- `GIT-08` 破坏性变更:`type` 后加 `!` 且 footer 写 `BREAKING CHANGE: <说明与迁移方式>`。
@@ -79,6 +79,30 @@ feat(media): 图片批次支持按规格矩阵展开任务项
Refs: R-25
```
### 2.1 中文书写与中英混排(GIT-21 ~ GIT-23)
- `GIT-21` 中文与英文 / 数字之间**加一个空格**(`新增 PRD V1.6`、`导出 50 张图`);标点用中文全角;代码、命令、文件名、版本号、错误码用反引号包裹并保留原文。
- `GIT-22` 术语沿用 PRD 附录 C 术语表,**禁止自造同义词**(「素材规格」不写「素材尺寸」,「要素卡」不写「简报卡」)。
- `GIT-23` 禁止 Chinglish 与无信息缩写:不写 `add 功能 for batch`、`opt`、`tmp`、`misc`、`update`;`type` / `scope` 之外的英文只能是专有名词、标识符或引用编号。
### 2.2 commitlint 配置要点
中文提交信息有三个坑,必须在 `commitlint.config.mjs` 中显式处理,否则校验形同无效:
```js
export default {
extends: ['@commitlint/config-conventional'],
rules: {
'subject-case': [0], // 中文无大小写概念,关闭该规则
'header-max-length': [2, 'always', 72], // 按字符计,中文每个字计 1
'subject-full-stop': [2, 'never', '。'], // 拦截中文句号
'subject-empty': [2, 'never'],
},
};
```
> 对应的 husky `commit-msg` 钩子见 [03-格式化与Lint](03-格式化与Lint.md) §4。
---
## 3 PR 与合并
@@ -115,7 +139,7 @@ Refs: R-25
## 6 检查清单(提交前 / 合并前)
- [ ] 分支名符合 `GIT-01`,从最新 `main` 拉出
- [ ] 提交信息符合 Conventional Commits,含 `scope`
- [ ] 提交信息为**中文**且符合 Conventional Commits(含 `scope`),subject 无句末标点
- [ ] 提交粒度单一,无无关文件
- [ ] 无 `.env` / 密钥 / 大文件
- [ ] PR 描述含背景 / 影响面 / 回滚方式 / 验证证据
+1 -1
View File
@@ -91,7 +91,7 @@ element-plus naive-ui @mui/* @chakra-ui/*
| 钩子 | 工具 | 行为 |
| --- | --- | --- |
| `pre-commit` | husky + lint-staged | 仅对暂存文件跑 `eslint --fix` + `prettier --write` |
| `commit-msg` | commitlint | 校验 Conventional Commits(见 [01](01-Git规范.md) §2) |
| `commit-msg` | commitlint | 校验 Conventional Commits 与中文书写(配置见 [01](01-Git规范.md) §2.2) |
| `pre-push` | husky | 跑 `pnpm typecheck`(本地拦截类型错误,避免浪费 CI) |
- `FMT-08` `lint-staged` 只处理暂存文件,**禁止**在钩子里跑全量 lint / 全量测试(太慢会诱发 `--no-verify`)。
@@ -32,7 +32,7 @@
- 迁移在 staging 的执行结果
```
- `PR-01` 标题遵循 Conventional Commits(Squash 后即主干提交)。
- `PR-01` 标题遵循 Conventional Commits 且**用中文**(Squash 时以 PR 标题为准,`scope` 保留英文,写法见 [01](01-Git规范.md) §2)。
- `PR-02` 变更 ≤ 400 行(不含 lock / 生成代码);超出拆分为多个 PR 并在描述写依赖顺序。
- `PR-03` 禁止在功能 PR 中混入无关重构、格式化、依赖升级。
- `PR-04` Draft PR 可用于早期讨论,但**不得**在 CI 未绿时请求 Review。
+1 -1
View File
@@ -20,7 +20,7 @@
| 项 | 约定 |
| --- | --- |
| 编写语言 | 中文说明 + 英文标识符 / 命令 / 路径 |
| 编写语言 | 中文说明 + 英文标识符 / 命令 / 路径;**Git 提交信息与 PR 标题也用中文**(见 [01](01-Git规范.md) §2) |
| 结构 | 作用与边界 → 规则(表格 / 编号)→ 检查清单 → 违规示例 |
| 变更 | 修改规则须单独 PR,说明「为什么改」+「存量代码如何处理」 |
| 版本 | `V<主>.<次>`;主版本 = 破坏性(存量代码需整改),次版本 = 补充 |