4.5 KiB
提交信息规范
本仓库的提交信息遵循 Conventional Commits 的首行结构，并在行首加一个 emoji 做视觉标记。描述用中文，类型关键字、作用域保持英文。
格式
一条提交信息只有一行，没有正文，也没有脚注：
<emoji> <type>[(scope)][!]: <中文描述>
<emoji>：下面表格里该类型对应的 emoji，后面跟一个空格。emoji 是必需的，且必须与本行类型一致——📝 docs:对，✨ docs:不对。<type>：小写英文关键字，见下表。(scope)：可选，改动范围。用()包住一个简短英文标识，例如docs(ci)、fix(client)、feat(host)。!：可选，紧跟在 type 或 scope 之后、冒号之前，表示破坏性变更。<描述>：中文，一句话，讲清这次改动做了什么；不换行、不用列表、不加句号。宽度不超过 72（中文字符按 2 个宽度算）。
不要写正文，也不要写脚注。 连 Refs: / Closes: / BREAKING CHANGE: 这类尾注也不写——需要交代的"为什么""影响面""迁移注意事项"，写进 README.md 或本文件，或写进代码注释，让说明跟着代码走，而不是埋在 git log 里。
破坏性变更只靠 ! 标记（例如 ♻️ refactor!: …）。这一条是对 Conventional Commits 的有意偏离：它要求破坏性变更必须有 BREAKING CHANGE: 脚注，本仓库不写脚注，所以判断破坏性变更以 ! 为准。
如果确实需要多行说明，说明这次改动不该只用一个提交标题交代——先补文档，再提交。
类型与 emoji
| 类型 | emoji | 码位 | 用途 |
|---|---|---|---|
feat |
✨ | U+2728 |
新增功能 |
fix |
🐛 | U+1F41B |
修复缺陷 |
docs |
📝 | U+1F4DD |
只改文档 |
refactor |
♻️ | U+267B U+FE0F |
重构，行为不变 |
perf |
⚡️ | U+26A1 U+FE0F |
性能优化 |
test |
✅ | U+2705 |
变更测试 |
build |
📦️ | U+1F4E6 U+FE0F |
构建系统或依赖 |
ci |
💚 | U+1F49A |
CI 配置 |
chore |
🔧 | U+1F527 |
杂项，以上都不属于时用 |
revert |
⏪️ | U+23EA U+FE0F |
回滚某次提交，正文写 Refs: <被回滚的提交> |
复制上表里的 emoji，不要手敲。 带 U+FE0F 的那五个是「基础字符 + 变体选择符」两个码位，手敲时很容易只打出前一个字符；对工具来说 ♻（U+267B）和 ♻️（U+267B U+FE0F）是两个不同的字符串，比对会失败。写规范或写脚本时，比较 emoji 前先做一次 NFC 归一化，或把两边都按 \uFE0F? 处理。
示例
每条都是一整条提交信息，就这一行：
✨ feat(client): 会话行悬停区加删除按钮
🐛 fix(host): 延迟删除台账只记录根会话
带作用域与破坏性标记（破坏性变更没有脚注，只看 !）：
♻️ refactor(client)!: 行内按钮改用自己的槽位 id
📝 docs: 安装说明改为只走 Git 标签与本地 tgz
工具链提示
emoji 在行首是本仓库的有意选择，视觉上整齐。代价是：以类型前缀开头的解析工具（commitlint、semantic-release、release-please 等）会读不到类型。如果以后要接这类工具，有两条路：
-
把 emoji 挪到冒号之后（
feat: ✨ 描述），类型回到行首，规范其余部分不变； -
保留行首 emoji，给工具写一个剥掉开头 emoji 与空格的预处理。可用的正则（
\p{Extended_Pictographic}已覆盖带与不带变体选择符两种写法）：^(?:\p{Extended_Pictographic}\uFE0F?\s+)?(?<type>[a-z]+)(?:\((?<scope>[^)]*)\))?(?<breaking>!)?:\s(?<desc>.+)$
自查
scripts/check-commit-log.mjs 会按本规范检查现有提交，只报告、不拦提交。除了首行格式，它还会报出任何带正文或脚注的提交：
node scripts/check-commit-log.mjs # 最近 10 条
node scripts/check-commit-log.mjs all # 全部
它从本文件的类型表里读 emoji 对照表，所以改了表不用改脚本。规范之前的提交不符合是正常的。
启用提交模板（可选）
.gitmessage 是提交信息模板。启用后每次 git commit 会带上前缀提示：
git config commit.template .gitmessage
模板整份都是 # 开头的注释，git 会自动丢弃，所以直接 git commit -m 也不受影响。只对当前仓库生效；换机器要重新执行一次。