# 版本维护

版本号与改动记录由 `scripts/version.mjs` 从 Git 历史计算。以下命令从仓库根目录执行：

```sh
node scripts/version.mjs --write
node scripts/version.mjs --check
node scripts/version.mjs --print
```

`--write` 写回派生文件，`--check` 检查当前版本是否与历史一致，`--print` 输出计算结果。

## 提交与版本规则

提交标题采用 Conventional Commits：`type(scope): 说明`。

| 当前区间内的提交 | 版本增量 |
| --- | --- |
| `BREAKING CHANGE:` 或 `type!:` | major |
| `feat` | minor |
| `fix` / `perf` | patch |
| 其他类型 | 版本号不变，更新构建号 |

构建号取 `git rev-list --count HEAD`。提交正文中以 `- ` 开头、且内容符合 `type(scope): 说明` 的行，也会作为独立条目归类，适合记录 squash 提交中的多项改动。历史发布按标签区间重新计算，不从上一次生成的文件续写。

## 派生文件

| 文件 | 用途 |
| --- | --- |
| `version.json` | 根固件的 `build.rs` 读取，编译期注入 `RMIC_VERSION*` |
| `docs/releases/changelog.md` | 供人阅读的改动记录 |
| `docs/releases/changelog.json` | 供程序读取的当前区间记录 |
| `desktop/src/lib/version.ts` | UI 版本标签与线路协议号 |
| `desktop/package.json`、`desktop/src-tauri/tauri.conf.json` 的 `version` | 安装包命名与系统中的应用版本 |

这些文件由同一次计算生成；改动记录应修改提交信息或生成脚本，再运行 `--write`。自动版本机制建立前的说明保存在[早期人工记录](../releases/changelog-legacy.md)。

## 固件与客户端的版本对应

版本沿 `git → version.json → 固件二进制 → Hello 报文 → 客户端界面` 传递。图传板每 2 秒广播语义化版本、构建号和编译时的线路协议号，布局见[UDP 协议](../protocol/udp.md#通告里的版本信息)。

设置中的绑定列表显示固件版本，裁判端在各路画面下方显示对应版本。线路协议不匹配时，客户端拒收视频并提示双方协议号，便于判断是否需要重烧固件或更换客户端。