From 229ff342d9f8ae5a1e84e4deabc47bfbb4632078 Mon Sep 17 00:00:00 2001 From: pyh Date: Wed, 30 Sep 2026 16:58:42 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20=E8=A7=84=E5=AE=9A?= =?UTF-8?q?=E6=8F=90=E4=BA=A4=E4=BF=A1=E6=81=AF=E5=8F=AA=E6=9C=89=E6=A0=87?= =?UTF-8?q?=E9=A2=98=E4=B8=8D=E8=A6=81=E6=AD=A3=E6=96=87=E4=B8=8E=E8=84=9A?= =?UTF-8?q?=E6=B3=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitmessage | 12 +++++----- CONTRIBUTING.md | 45 ++++++++++++------------------------ scripts/check-commit-log.mjs | 38 ++++++++++++++++++++---------- 3 files changed, 47 insertions(+), 48 deletions(-) diff --git a/.gitmessage b/.gitmessage index cb9503b..ab47a77 100644 --- a/.gitmessage +++ b/.gitmessage @@ -1,10 +1,10 @@ -# [(scope)][!]: <中文描述，一句话，首行只有一行，不超过 72 宽度，不加句号> +# [(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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c9cbb5..9f9d8e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,28 +1,26 @@ # 提交信息规范 -本仓库的提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 的结构，并在行首加一个 emoji 做视觉标记。**描述用中文**，类型关键字、作用域、脚注关键字保持英文。 +本仓库的提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 的**首行**结构，并在行首加一个 emoji 做视觉标记。**描述用中文**，类型关键字、作用域保持英文。 ## 格式 -提交信息分三段，除首行外都可省略： +**一条提交信息只有一行**，没有正文，也没有脚注： ```text - [(scope)][!]: <描述> ← 首行，必写，永远只有一行 - ← 一个空行分隔（没有正文时连空行也不要） -[正文：可多段多行，说清为什么这么改] ← 可选 - ← 一个空行分隔（没有脚注时可省略） -[脚注：Refs: / Closes: / BREAKING CHANGE:] ← 可选 + [(scope)][!]: <中文描述> ``` - ``：下面表格里该类型对应的 emoji，后面跟**一个空格**。emoji 是必需的，且必须与本行类型一致——`📝 docs:` 对，`✨ docs:` 不对。 - ``：小写英文关键字，见下表。 - `(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` 也不受影响。只对当前仓库生效；换机器要重新执行一次。 diff --git a/scripts/check-commit-log.mjs b/scripts/check-commit-log.mjs index 03760e1..a88e13d 100644 --- a/scripts/check-commit-log.mjs +++ b/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+)?' + '(?[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('缺少类型前缀，或整体格式不是 [(scope)][!]: <描述>') + notes.push('首行缺少类型前缀，或整体格式不是 [(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)