# 提交规则

## 提交格式

统一使用：

```text
编号:类型:说明
```

示例：

```text
001:新增:初始化 AstrBot for Android 项目
002:修复:修正服务停止后首页按钮状态
003:更新:优化内置后台默认缩放比例
004:文档:完善源码构建与更新说明
```

编号使用至少三位数字，从 `001` 开始，按主分支已有编号递增；超过 `999` 后继续使用 `1000`、`1001`。提交前查看近期历史，分支合并前核对编号；已公开的提交不因重新编号而改写历史。

类型和说明之间使用英文冒号。说明使用中文，直接写清楚改了什么，不使用“修改一些东西”“临时提交”等模糊描述。

## 类型

| 类型 | 用途 |
| --- | --- |
| `新增` | 新增功能、页面、脚本或配置 |
| `修复` | 修复错误、兼容性问题或异常行为 |
| `更新` | 调整已有功能、交互、默认值或依赖版本 |
| `重构` | 在保持现有行为的前提下整理代码结构 |
| `文档` | 更新 README、使用说明、开发文档或注释 |
| `清理` | 删除无用文件、旧实现或过期内容 |
| `回滚` | 撤销某次改动，说明中写明原因或目标编号 |

## 提交约定

- 一个提交解决一件相关的事情。功能修改、无关的格式调整和目录清理尽量分开。
- 说明可以简短；涉及配置迁移、数据兼容、依赖变化或重要取舍时，在提交正文中补充原因和影响。
- 功能或默认行为变化时，同步更新使用说明；公开版本的变化记入 `docs/CHANGELOG.md`。
- 新增公共文档时，同步维护相关入口和源码收集白名单，确保源码包中的文档链接有效。
- 第三方依赖或运行环境变化时，同步更新来源、版本锁、摘要和适用的许可材料，不手工篡改摘要来跳过校验。
- 修复问题时运行对应检查；界面或设备兼容改动在 PR 中注明检查方式、设备和 Android 版本。个人调试记录保存在已忽略的 `.local/testing/` 或工程外。

提交前先检查文件范围和差异：

```bash
git status --short
git diff --check
git diff
# 明确选择本次修改的文件后，再检查暂存内容
git diff --cached --check
git diff --cached
git commit -m "005:修复:修正后台页面重试状态"
```

检查命令和开发环境见 [参与开发](CONTRIBUTING.md)。纯文档修改检查内容与链接即可；代码、构建或运行环境修改执行与影响范围对应的检查。

## 不提交的内容

- APK、AAB、运行镜像、预编译程序、构建输出和缓存。
- QQ 会话、账号配置、API Key、访问口令、备份和手机导出的日志。
- Android 签名密钥、更新目录私钥、本机 `local.properties` 和个人环境配置。
- 个人设备记录、验收表、实施过程、临时截图和开发笔记。

构建所需的来源、锁文件和准备脚本保留在仓库。大型文件放在工程外或合适的 Release 附件中；公开界面截图放在 `docs/images/`，发布前移除其中的账号和凭据信息。

## 版本号规则

管理器使用语义化版本：`MAJOR.MINOR.PATCH`，Git 标签为 `vMAJOR.MINOR.PATCH`。版本由 `gradle.properties` 中的 `appVersionName`、`appVersionCode` 管理，构建时可通过同名 `-P` 参数覆盖。

| 改动 | 版本变化 | 示例 |
| --- | --- | --- |
| 兼容现有配置的新功能 | MINOR +1，PATCH 归零 | `1.0.2` → `1.1.0` |
| 兼容性修复或错误修复 | PATCH +1 | `1.0.0` → `1.0.1` |
| 无法兼容旧版的配置、数据或使用方式变化 | MAJOR +1，MINOR / PATCH 归零 | `1.2.0` → `2.0.0` |
| 文档、清理和不改变行为的重构 | 通常随下一次功能或修复发布 | — |

是否升级版本以及升级哪一位，以实际行为和兼容性为准，不仅由提交类型决定。兼容性变化需要说明迁移或恢复方式。

- 首个正式版本使用 `appVersionName=1.0.0`、`appVersionCode=10000`。
- 每次公开 APK 更新都必须提高 `appVersionCode`；它独立于提交编号，不能只改 `appVersionName`。
- 版本号在实际发布时确定。开发中的多次修改可以合并为同一个待发布版本，不为每次提交单独发版，也不为未发布的中间状态跳号。
- 发布前核对版本参数、README 版本标识、`docs/CHANGELOG.md` 和 Git 标签保持一致。
- AstrBot、NapCat、QQ 等组件保留各自的上游版本，不跟随管理器版本一起改号。
- 更新目录的 `sequence` 独立递增，与管理器版本号、提交编号分开管理。

## 发布约定

正式 APK 使用包名 `io.astrbot.android` 和固定的长期签名。带 `.offlinecheck` 等后缀的本地包及 Debug 签名包，不作为正式更新通道的安装包。

长期签名密钥及密码保存在 Git 已忽略的 `.local/signing/`，备份整个目录并持续复用。正式包可通过根目录 `build.bat` 或 `tools/build_release.py` 构建；脚本核对签名指纹，禁止用新密钥替代已建立的签名身份。

发布时先确定版本，完成对应检查、正式签名和发行材料，再创建匹配的 Git 标签并发布 Release；签名更新目录按[更新与分发](../docs/更新与分发.md)中的顺序生成和发布。

已公开的标签和安装包保留原始内容。发布后需要修复时，发布新版本，不覆盖同一个版本的安装包；本地开发和 NAS 测试目录可以覆盖候选包。

GitHub Actions 执行源码检查，并独立续签 `updates` 分支的已有更新目录，不自动引入组件新版本。推送 `v*` 标签不会自动构建 APK 或创建 Release。更新目录分支的自动提交按该分支历史独立编号。