# 提交信息规范

本仓库的提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 的**首行**结构，并在行首加一个 emoji 做视觉标记。**描述用中文**，类型关键字、作用域保持英文。

## 格式

**一条提交信息只有一行**，没有正文，也没有脚注：

```text
<emoji> <type>[(scope)][!]: <中文描述>
```

- `<emoji>`：下面表格里该类型对应的 emoji，后面跟**一个空格**。emoji 是必需的，且必须与本行类型一致——`📝 docs:` 对，`✨ docs:` 不对。
- `<type>`：小写英文关键字，见下表。
- `(scope)`：可选，改动范围。用 `()` 包住一个简短英文标识，例如 `fix(client)`、`fix(host)`、`docs(ci)`。
- `!`：可选，紧跟在 type 或 scope 之后、冒号之前，表示破坏性变更。
- `<描述>`：中文，一句话，讲清这次改动做了什么；不换行、不用列表、不加句号。宽度不超过 72（中文字符按 2 个宽度算）。

**不要写正文，也不要写脚注。** 连 `Refs:` / `Closes:` / `BREAKING CHANGE:` 这类尾注也不写——需要交代的"为什么""影响面""迁移注意事项"，写进 [README.md](README.md)、[CHANGELOG.md](CHANGELOG.md) 或本文件，或写进代码注释，让说明跟着代码走，而不是埋在 `git log` 里。

**破坏性变更只靠 `!` 标记**（例如 `♻️ refactor!: …`）。这一条是对 Conventional Commits 的有意偏离：它要求破坏性变更必须有 `BREAKING CHANGE:` 脚注，本仓库不写脚注，所以判断破坏性变更以 `!` 为准。

如果确实需要多行说明，说明这次改动不该只用一个提交标题交代——先补文档（这个插件的版本级说明进 [CHANGELOG.md](CHANGELOG.md)），再提交。

## 类型与 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?` 处理。

## 作用域约定

这个插件只有一个包，作用域用来区分改动落在哪一半，不是必需的：

- `client`：浏览器半（`client.js`）—— 通知引擎、轻弹窗、插件页配置、观察器；
- `host`：宿主半（`index.js`、`cordis.patch.yml`）—— 目前是空壳，只有它变化时才需要重启 DSH；
- 其它临时作用域（如 `deps`、`naming`）按需起，不必登记。

## 示例

每条都是一整条提交信息，就这一行：

```text
✨ feat(client): 后台走系统通知，前台走应用内轻弹窗
```

```text
🐛 fix(client): 前台判定改为现读可见性，不再只信 blur 事件
```

带作用域与破坏性标记（破坏性变更**没有**脚注，只看 `!`）：

```text
♻️ refactor(client)!: 配置从通用设置挪到插件页
```

```text
📝 docs: 安装说明补充 Git 标签与本地路径两种方式
```

## 工具链提示

emoji 在行首是本仓库的有意选择，视觉上整齐。代价是：以类型前缀开头的解析工具（`commitlint`、`semantic-release`、`release-please` 等）会读不到类型。如果以后要接这类工具，有两条路：

1. 把 emoji 挪到冒号之后（`feat: ✨ 描述`），类型回到行首，规范其余部分不变；
2. 保留行首 emoji，给工具写一个剥掉开头 emoji 与空格的预处理。可用的正则（`\p{Extended_Pictographic}` 已覆盖带与不带变体选择符两种写法）：

   ```text
   ^(?:\p{Extended_Pictographic}\uFE0F?\s+)?(?<type>[a-z]+)(?:\((?<scope>[^)]*)\))?(?<breaking>!)?:\s(?<desc>.+)$
   ```

## 自查

`scripts/check-commit-log.mjs` 会按本规范检查现有提交，只报告、不拦提交。除了首行格式，它还会报出**任何带正文或脚注的提交**：

```bash
node scripts/check-commit-log.mjs        # 最近 10 条
node scripts/check-commit-log.mjs all    # 全部
DN_SPEC=path/to/CONTRIBUTING.md node scripts/check-commit-log.mjs   # 换一份规范文件（可选）
```

它从本文件的类型表里读 emoji 对照表，所以改了表不用改脚本。

## 启用提交模板（可选）

`.gitmessage` 是提交信息模板。启用后每次 `git commit` 会带上前缀提示：

```bash
git config commit.template .gitmessage
```

模板整份都是 `#` 开头的注释，git 会自动丢弃，所以直接 `git commit -m` 也不受影响。只对当前仓库生效；换机器要重新执行一次。