# PR 规范

本文档用于说明向 MAA Meow 提交 Pull Request（PR）时的基本约定，帮助贡献者和维护者更快确认改动范围、验证结果与合并风险。

## 基本原则

- **目标分支**：默认提交到 `main` 分支。
- **范围单一**：一个 PR 只解决一个明确问题，避免混入无关重构、格式化或依赖更新。
- **说明完整**：PR 描述应写清楚改动原因、影响范围、验证方式和已知风险。
- **尽早 Draft**：需求或实现方向尚未确定时，请先创建 Draft PR，方便提前讨论。
- **自己负责**：可以使用 AI 辅助，但提交者必须理解并能解释 PR 中的关键改动。

## 分支与提交

### 分支命名

推荐使用以下格式：

| 类型 | 示例 | 适用场景 |
|------|------|----------|
| `feat/<name>` | `feat/schedule-profile` | 新增功能 |
| `fix/<name>` | `fix/background-service` | 修复 Bug |
| `docs/<name>` | `docs/pr-guidelines` | 文档改动 |
| `refactor/<name>` | `refactor/task-runner` | 不改变行为的结构调整 |
| `chore/<name>` | `chore/update-gradle` | 构建、依赖、工具等维护工作 |

### 提交信息

推荐遵循 [约定式提交（Conventional Commits）](https://www.conventionalcommits.org/zh-hans/v1.0.0/)：

```text
<type>(<scope>): <subject>
```

示例：

```text
feat(schedule): 添加定时任务配置
fix(background): 修复后台任务启动失败
docs: 补充 PR 规范
```

`scope` 可选，建议填写影响范围。`subject` 使用简短描述，不以句号结尾。

## PR 标题

PR 标题建议与提交信息保持一致，方便维护者快速判断变更类型：

| 推荐标题 | 不推荐标题 |
|----------|------------|
| `feat(schedule): 添加定时任务配置` | `添加新功能` |
| `fix(background): 修复后台任务启动失败` | `修一下后台` |
| `docs: 补充构建说明` | `update docs` |

如果 PR 仍在开发中，请使用 GitHub Draft PR，而不是在标题前长期保留 `WIP`。

## PR 描述

PR 描述至少应包含以下信息：

### 关联内容

- 关联 Issue：`Closes #123`、`Fixes #123` 或 `Related #123`
- 如果没有 Issue，请说明需求来源、复现方式或为什么需要这个改动

### 变更摘要

用 2～5 条 bullet 说明改了什么，例如：

- 调整后台任务启动流程
- 新增 Profile 配置校验
- 更新构建文档中的 JDK 要求

### 验证记录

说明你做过哪些验证。不要只写“已测试”，应写清楚设备、系统版本、权限方案、执行命令或操作路径。

推荐格式：

```markdown
## 验证

- [x] Android Studio Sync Project with Gradle Files 成功
- [x] 执行 `./gradlew assembleDebug` 成功
- [x] Android 14 / Shizuku 环境下验证后台模式可启动任务
```

### 截图、日志与素材

涉及 UI、权限、后台服务、任务执行或 Bug 修复时，应尽量提供：

- 修改前后的截图或录屏
- 崩溃堆栈、Logcat 关键片段或 GitHub Actions 链接
- 复现步骤、测试设备、Android 版本与权限方案（Shizuku / Root）
- 对 MAA Core、资源文件或第三方依赖的影响说明

## 变更要求

### Android / Kotlin 改动

- 保持代码路径清晰，避免把 UI、权限、后台服务与任务调度逻辑揉在同一个大函数里。
- 修改权限、后台执行、通知、无障碍或 Shizuku / Root 相关逻辑时，需要说明兼容性影响。
- 新增用户可见配置、文案或交互时，应同步更新相关文档或截图说明。
- 涉及长时间运行任务时，应考虑取消、异常处理和资源释放路径。

### 构建与依赖改动

- 修改 Gradle、JDK、Android SDK、NDK、CMake 或工作流配置时，应说明动机和影响范围。
- 依赖升级需要提交对应锁定/配置文件变更，并说明是否影响最低系统版本或 ABI。
- 不要提交本地构建产物、IDE 缓存、下载得到的大体积资源或调试文件。

### 文档改动

- 用户可见行为、构建步骤、权限要求或自动化接口发生变化时，应同步更新文档。
- 中英 README 中已有对应入口时，建议同时维护，避免两个入口的信息不一致。
- 文档链接应使用仓库内相对路径，避免绑定到固定分支或个人 fork。

## 提交前检查清单

提交 PR 前至少自查：

- [ ] PR 目标分支是 `main`
- [ ] PR 标题清晰，最好符合约定式提交格式
- [ ] 变更范围单一，没有混入无关改动
- [ ] 已同步最新 `origin/main`
- [ ] 已说明变更原因、影响范围和验证结果
- [ ] 涉及 Android 行为时，已说明测试设备、系统版本和权限方案
- [ ] 涉及构建、依赖或工作流时，已提供对应命令或 Actions 验证结果
- [ ] 文档已随用户可见行为或开发约定同步更新
- [ ] 没有提交缓存、构建产物、调试文件或大体积资源

## 评审与合并

- 维护者可能要求补充日志、截图、复现步骤或验证记录；请在同一 PR 中继续修正。
- 如果评审意见涉及设计方向，请先回复确认方案，再继续大量改动。
- PR 被合并后，如发现后续问题，请新开 Issue 或 PR 跟进，不要在已合并 PR 中继续讨论新的无关需求。