📝 docs: 规定提交信息只有标题不要正文与脚注

.gitmessage

@@ -1,10 +1,10 @@
-# <emoji> <type>[(scope)][!]: <中文描述，一句话，首行只有一行，不超过 72 宽度，不加句号>
+# <emoji> <type>[(scope)][!]: <中文描述，一句话，不加句号>
+# 一条提交信息只有这一行，不写正文，也不写脚注。
+# 破坏性变更只用 ! 标记，例如：♻️ refactor!: 改掉了某某行为
+# 需要交代背景时，把说明写进 README.md、CONTRIBUTING.md 或代码注释。
+#
 # 类型与 emoji：feat ✨ / fix 🐛 / docs 📝 / refactor ♻️ / perf ⚡️ /
 #              test ✅ / build 📦️ / ci 💚 / chore 🔧 / revert ⏪️
 # 例：✨ feat(client): 会话行悬停区加删除按钮
 # 例：🐛 fix(host): 延迟删除台账只记录根会话
-#
-# ↓ 正文（可省略，可多段）：为什么这么改、影响面、迁移注意事项，每行不超过 72 宽度
-#
-#
-# ↓ 脚注（可省略）：Refs: #12 / Closes: #34 / BREAKING CHANGE: <中文说明>
+# 例：📝 docs(ci): 安装说明只保留 Git 标签与本地 tgz

CONTRIBUTING.md

@@ -1,28 +1,26 @@
 # 提交信息规范
 
-本仓库的提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 的结构，并在行首加一个 emoji 做视觉标记。**描述用中文**，类型关键字、作用域、脚注关键字保持英文。
+本仓库的提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 的**首行**结构，并在行首加一个 emoji 做视觉标记。**描述用中文**，类型关键字、作用域保持英文。
 
 ## 格式
 
-提交信息分三段，除首行外都可省略：
+**一条提交信息只有一行**，没有正文，也没有脚注：
 
 ```text
-<emoji> <type>[(scope)][!]: <描述>          ← 首行，必写，永远只有一行
-                                             ← 一个空行分隔（没有正文时连空行也不要）
-[正文：可多段多行，说清为什么这么改]           ← 可选
-                                             ← 一个空行分隔（没有脚注时可省略）
-[脚注：Refs: / Closes: / BREAKING CHANGE:]   ← 可选
+<emoji> <type>[(scope)][!]: <中文描述>
 ```
 
 - `<emoji>`：下面表格里该类型对应的 emoji，后面跟**一个空格**。emoji 是必需的，且必须与本行类型一致——`📝 docs:` 对，`✨ docs:` 不对。
 - `<type>`：小写英文关键字，见下表。
 - `(scope)`：可选，改动范围。用 `()` 包住一个简短英文标识，例如 `docs(ci)`、`fix(client)`、`feat(host)`。
 - `!`：可选，紧跟在 type 或 scope 之后、冒号之前，表示破坏性变更。
-- `<描述>`：中文，**一句话**，讲清这次改动做了什么；不换行、不用列表、不加句号。首行宽度不超过 72（中文字符按 2 个宽度算）。
-- 正文：可选，中文，可以多段多行，每行不超过 72 个宽度。写"为什么这么改""影响面""迁移要注意什么"，不要复述 diff。描述一句话讲得清时就不要写正文。
-- 脚注：可选（破坏性变更除外），关键字用英文。破坏性变更必须写 `BREAKING CHANGE: <中文说明>`，不能只靠 `!`。
+- `<描述>`：中文，一句话，讲清这次改动做了什么；不换行、不用列表、不加句号。宽度不超过 72（中文字符按 2 个宽度算）。
 
-上面说的"单行"指的是**首行只有一行**（不用列表、不折行）——正文是另一回事，需要时就写，多写几段不算违规。别把两者混起来：没有正文是允许的，不是要求。
+**不要写正文，也不要写脚注。** 连 `Refs:` / `Closes:` / `BREAKING CHANGE:` 这类尾注也不写——需要交代的"为什么""影响面""迁移注意事项"，写进 [README.md](README.md) 或本文件，或写进代码注释，让说明跟着代码走，而不是埋在 `git log` 里。
+
+**破坏性变更只靠 `!` 标记**（例如 `♻️ refactor!: …`）。这一条是对 Conventional Commits 的有意偏离：它要求破坏性变更必须有 `BREAKING CHANGE:` 脚注，本仓库不写脚注，所以判断破坏性变更以 `!` 为准。
+
+如果确实需要多行说明，说明这次改动不该只用一个提交标题交代——先补文档，再提交。
 
 ## 类型与 emoji
 
@@ -43,35 +41,22 @@
 
 ## 示例
 
-新增功能：
+每条都是一整条提交信息，就这一行：
 
 ```text
 ✨ feat(client): 会话行悬停区加删除按钮
-
-官方 archive 与 pin 两个悬停按钮保持原位，本插件的删除按钮插在两者
-之间，不再借用 archive 的 id 压级替换。
 ```
 
-修复缺陷：
-
 ```text
 🐛 fix(host): 延迟删除台账只记录根会话
-
-台账原先记录整棵树，但启动清扫以根为单位整棵删除，导致子会话被重复
-删除并重复广播 api-session/removed。
 ```
 
-破坏性变更：
+带作用域与破坏性标记（破坏性变更**没有**脚注，只看 `!`）：
 
 ```text
-♻️ refactor!: 行内按钮改用自己的槽位 id
-
-BREAKING CHANGE: 悬停区布局变化，官方归档按钮回到原来的位置。按住旧
-结构写样式的用户需要调整。
+♻️ refactor(client)!: 行内按钮改用自己的槽位 id
 ```
 
-纯文档：
-
 ```text
 📝 docs: 安装说明改为只走 Git 标签与本地 tgz
 ```
@@ -89,7 +74,7 @@ emoji 在行首是本仓库的有意选择，视觉上整齐。代价是：以
 
 ## 自查
 
-`scripts/check-commit-log.mjs` 会按本规范检查现有提交的首行，只报告、不拦提交：
+`scripts/check-commit-log.mjs` 会按本规范检查现有提交，只报告、不拦提交。除了首行格式，它还会报出**任何带正文或脚注的提交**：
 
 ```bash
 node scripts/check-commit-log.mjs        # 最近 10 条
@@ -100,10 +85,10 @@ node scripts/check-commit-log.mjs all    # 全部
 
 ## 启用提交模板（可选）
 
-`.gitmessage` 是提交信息模板。启用后每次 `git commit` 会带上前缀提示，删掉不需要的部分即可：
+`.gitmessage` 是提交信息模板。启用后每次 `git commit` 会带上前缀提示：
 
 ```bash
 git config commit.template .gitmessage
 ```
 
-模板里以 `#` 开头的行会被 git 自动丢弃，不会进入提交信息。只对当前仓库生效；换机器要重新执行一次。
+模板整份都是 `#` 开头的注释，git 会自动丢弃，所以直接 `git commit -m` 也不受影响。只对当前仓库生效；换机器要重新执行一次。

scripts/check-commit-log.mjs

@@ -1,6 +1,6 @@
-// Checks real commit subjects (newest first) against the CONTRIBUTING.md spec:
-// the documented regex must parse them, the leading emoji must be present and
-// match the type table exactly, and the subject must stay within 72 width.
+// Checks existing commits against the CONTRIBUTING.md spec. The spec allows one
+// line only, so a subject must both parse (emoji + type + Chinese description)
+// and be the whole message: any body or footer is reported too.
 //
 // This is a reporting tool, not a hook: it never blocks a commit.
 //
@@ -19,7 +19,7 @@ const specPath = process.env.DSD_SPEC ?? resolve(repoRoot, 'CONTRIBUTING.md')
 const doc = readFileSync(specPath, 'utf8')
 const count = process.argv[2] ?? '10'
 
-/** The regex the spec documents for stripping a leading emoji. */
+/** The regex the spec documents for a subject line. */
 const SUBJECT = new RegExp(
   '^(?:\\p{Extended_Pictographic}\\uFE0F?\\s+)?' +
   '(?<type>[a-z]+)' +
@@ -43,17 +43,29 @@ const base = (text) => text.replace(/\uFE0F/g, '')
 /** Display width, counting anything above U+2000 as double. */
 const widthOf = (text) => [...text].reduce((n, c) => n + (c.codePointAt(0) > 0x2000 ? 2 : 1), 0)
 
-const args = count === 'all' ? ['log', '--format=%h%x09%s'] : ['log', `-${Number(count)}`, '--format=%h%x09%s']
-const rows = execFileSync('git', args, { encoding: 'utf8', cwd: repoRoot })
-  .trim().split('\n').filter((line) => line !== '')
+// %B is the raw message body, so a record can hold several lines: a record ends
+// at the next hash that starts a line, which is what this splits on.
+const range = count === 'all' ? [] : [`-${Number(count)}`]
+const raw = execFileSync('git', ['log', ...range, '--format=%h%x09%B%x00'], {
+  encoding: 'utf8',
+  cwd: repoRoot,
+})
+
+const commits = raw.split('\0').map((chunk) => chunk.replace(/^\n+/, '')).filter((chunk) => chunk.trim() !== '')
 
 let problems = 0
-for (const row of rows) {
-  const [hash, subject] = row.split('\t')
+for (const chunk of commits) {
+  const tab = chunk.indexOf('\t')
+  const hash = chunk.slice(0, tab)
+  const message = chunk.slice(tab + 1).replace(/\n+$/, '')
+  const lines = message.split('\n')
+  const subject = lines[0]
+  const extra = lines.slice(1).filter((line) => line.trim() !== '')
   const notes = []
+
   const match = SUBJECT.exec(subject)
   if (match === null) {
-    notes.push('缺少类型前缀，或整体格式不是 <emoji> <type>[(scope)][!]: <描述>')
+    notes.push('首行缺少类型前缀，或整体格式不是 <emoji> <type>[(scope)][!]: <描述>')
   } else {
     const expected = emojiOfType.get(match.groups.type)
     const lead = [...subject][0]
@@ -63,12 +75,14 @@ for (const row of rows) {
     if (width > 72) notes.push(`首行宽度 ${width}，超过 72`)
     if (/[。.]$/.test(subject)) notes.push('首行结尾不应有句号')
   }
+  if (extra.length > 0) notes.push(`带了 ${extra.length} 行正文或脚注，规范要求只有一行`)
+
   if (notes.length > 0) problems += 1
   const mark = notes.length === 0 ? 'ok  ' : 'FAIL'
   console.log(`  ${mark} ${hash} ${notes.length === 0 ? '' : notes.join('；') + ' — '}${subject}`)
 }
 
 console.log(problems === 0
-  ? `\n检查了 ${rows.length} 条提交，全部符合规范`
-  : `\n检查了 ${rows.length} 条提交，其中 ${problems} 条不符合规范（规范文件：${specPath}）`)
+  ? `\n检查了 ${commits.length} 条提交，全部符合规范`
+  : `\n检查了 ${commits.length} 条提交，其中 ${problems} 条不符合规范（规范文件：${specPath}）`)
 process.exit(problems === 0 ? 0 : 1)