diff --git a/.gitmessage b/.gitmessage index 29c3abd..cb9503b 100644 --- a/.gitmessage +++ b/.gitmessage @@ -1,10 +1,10 @@ -# [(scope)][!]: <中文描述,不超过 72 宽度,不加句号> +# [(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: <中文说明> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 91272dc..6c9cbb5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,21 +4,25 @@ ## 格式 +提交信息分三段,除首行外都可省略: + ```text - [(scope)][!]: <描述> -<空行> -[正文:为什么这么改、影响面、迁移注意事项] -<空行> -[脚注:Refs: #12 / Closes: #34 / BREAKING CHANGE: ...] + [(scope)][!]: <描述> ← 首行,必写,永远只有一行 + ← 一个空行分隔(没有正文时连空行也不要) +[正文:可多段多行,说清为什么这么改] ← 可选 + ← 一个空行分隔(没有脚注时可省略) +[脚注:Refs: / Closes: / BREAKING CHANGE:] ← 可选 ``` - ``:下面表格里该类型对应的 emoji,后面跟**一个空格**。emoji 是必需的,且必须与本行类型一致——`📝 docs:` 对,`✨ docs:` 不对。 - ``:小写英文关键字,见下表。 - `(scope)`:可选,改动范围。用 `()` 包住一个简短英文标识,例如 `docs(ci)`、`fix(client)`、`feat(host)`。 - `!`:可选,紧跟在 type 或 scope 之后、冒号之前,表示破坏性变更。 -- `<描述>`:中文,一句话,讲清这次改动做了什么。**首行不超过 72 个字符**(中文字符按 2 个宽度算),结尾不加句号。 -- 正文:中文,每行不超过 72 个宽度。说清"为什么",不要复述 diff。单行描述足以讲明白时就省略。 -- 脚注:破坏性变更必须写 `BREAKING CHANGE: <中文说明>`,不能只靠 `!`。 +- `<描述>`:中文,**一句话**,讲清这次改动做了什么;不换行、不用列表、不加句号。首行宽度不超过 72(中文字符按 2 个宽度算)。 +- 正文:可选,中文,可以多段多行,每行不超过 72 个宽度。写"为什么这么改""影响面""迁移要注意什么",不要复述 diff。描述一句话讲得清时就不要写正文。 +- 脚注:可选(破坏性变更除外),关键字用英文。破坏性变更必须写 `BREAKING CHANGE: <中文说明>`,不能只靠 `!`。 + +上面说的"单行"指的是**首行只有一行**(不用列表、不折行)——正文是另一回事,需要时就写,多写几段不算违规。别把两者混起来:没有正文是允许的,不是要求。 ## 类型与 emoji