📝 docs: 讲清"单行"指首行,正文不禁止
之前的措辞容易被读成"提交信息只能有一行"。现在把三段结构摆出来,并写明 首行、正文、脚注各自的要求与宽度上限,正文和脚注都标注为可省略。 顺带说明:正文不是违规内容,没有正文是允许而不是必须。
This commit is contained in:
+2
-2
@@ -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
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user