📝 docs: 讲清"单行"指首行,正文不禁止

之前的措辞容易被读成"提交信息只能有一行"。现在把三段结构摆出来,并写明
首行、正文、脚注各自的要求与宽度上限,正文和脚注都标注为可省略。

顺带说明:正文不是违规内容,没有正文是允许而不是必须。
This commit is contained in:
pyh
2026-09-30 16:56:04 +08:00
parent 83eae74f63
commit 07f5af6fff
2 changed files with 14 additions and 10 deletions
+2 -2
View File
@@ -1,10 +1,10 @@
# <emoji> <type>[(scope)][!]: <中文描述,不超过 72 宽度,不加句号>
# <emoji> <type>[(scope)][!]: <中文描述,一句话,首行只有一行,不超过 72 宽度,不加句号>
# 类型与 emoji:feat ✨ / fix 🐛 / docs 📝 / refactor ♻️ / perf ⚡️ /
# test ✅ / build 📦️ / ci 💚 / chore 🔧 / revert ⏪️
# 例:✨ feat(client): 会话行悬停区加删除按钮
# 例:🐛 fix(host): 延迟删除台账只记录根会话
#
# ↓ 正文(可省略):为什么这么改、影响面、迁移注意事项,每行不超过 72 宽度
# ↓ 正文(可省略,可多段):为什么这么改、影响面、迁移注意事项,每行不超过 72 宽度
#
#
# ↓ 脚注(可省略):Refs: #12 / Closes: #34 / BREAKING CHANGE: <中文说明>
+12 -8
View File
@@ -4,21 +4,25 @@
## 格式
提交信息分三段,除首行外都可省略:
```text
<emoji> <type>[(scope)][!]: <描述>
<空行>
[正文:为什么这么改、影响面、迁移注意事项]
<空行>
[脚注:Refs: #12 / Closes: #34 / BREAKING CHANGE: ...]
<emoji> <type>[(scope)][!]: <描述> ← 首行,必写,永远只有一行
← 一个空行分隔(没有正文时连空行也不要)
[正文:可多段多行,说清为什么这么改] ← 可选
← 一个空行分隔(没有脚注时可省略)
[脚注:Refs: / Closes: / BREAKING CHANGE:] ← 可选
```
- `<emoji>`:下面表格里该类型对应的 emoji,后面跟**一个空格**。emoji 是必需的,且必须与本行类型一致——`📝 docs:` 对,`✨ docs:` 不对。
- `<type>`:小写英文关键字,见下表。
- `(scope)`:可选,改动范围。用 `()` 包住一个简短英文标识,例如 `docs(ci)`、`fix(client)`、`feat(host)`。
- `!`:可选,紧跟在 type 或 scope 之后、冒号之前,表示破坏性变更。
- `<描述>`:中文,一句话,讲清这次改动做了什么。**首行不超过 72 个字符**(中文字符按 2 个宽度算),结尾不加句号。
- 正文:中文,每行不超过 72 个宽度。说清"为什么",不要复述 diff。单行描述足以讲明白时就省略。
- 脚注:破坏性变更必须写 `BREAKING CHANGE: <中文说明>`,不能只靠 `!`。
- `<描述>`:中文,**一句话**,讲清这次改动做了什么;不换行、不用列表、不加句号。首行宽度不超过 72(中文字符按 2 个宽度算)。
- 正文:可选,中文,可以多段多行,每行不超过 72 个宽度。写"为什么这么改""影响面""迁移要注意什么",不要复述 diff。描述一句话讲得清时就不要写正文。
- 脚注:可选(破坏性变更除外),关键字用英文。破坏性变更必须写 `BREAKING CHANGE: <中文说明>`,不能只靠 `!`。
上面说的"单行"指的是**首行只有一行**(不用列表、不折行)——正文是另一回事,需要时就写,多写几段不算违规。别把两者混起来:没有正文是允许的,不是要求。
## 类型与 emoji