# 贡献指南

感谢你对本项目的关注与支持！🎉

欢迎通过提交 Issue、Pull Request、修复 Bug、完善文档或提出新功能建议等方式参与项目建设。

在开始贡献之前，请阅读以下说明，以便我们更高效地进行协作。

---

## 1. 贡献方式

你可以通过以下方式参与项目：

* 提交 Bug 报告
* 提出新功能建议
* 修复已有问题
* 优化代码结构或性能
* 改进 UI / UX
* 完善项目文档
* 补充注释
* 优化兼容性
* 提交新的功能实现

---

## 2. 提交 Issue

如果你发现了 Bug 或有新的功能建议，请优先创建一个 Issue。

提交 Bug 时，建议尽量包含以下信息：

* 问题描述
* 出现问题的版本
* Android / 系统版本
* 设备型号
* 复现步骤
* 预期行为
* 实际行为
* 错误日志
* 截图或录屏（如果有）

例如：

```text
问题：
进入游戏库页面后，上拉无法加载下一页。

复现步骤：
1. 打开应用
2. 进入游戏库
3. 滚动到底部
4. 继续上拉

预期行为：
加载下一页游戏。

实际行为：
没有触发任何加载操作。

设备：
Android 15
```

对于功能建议，请尽量说明：

```text
功能：
希望增加游戏收藏功能。

用途：
方便用户快速找到常玩的游戏。

建议实现：
在游戏卡片增加收藏按钮，并增加一个“收藏”分类。
```

---

## 3. Fork 项目

首先 Fork 本项目到自己的 GitHub 账号。

然后克隆你的仓库：

```bash
git clone https://github.com/YOUR_USERNAME/PROJECT_NAME.git
```

进入项目目录：

```bash
cd PROJECT_NAME
```

添加原仓库作为上游仓库：

```bash
git remote add upstream https://github.com/ORIGINAL_OWNER/PROJECT_NAME.git
```

查看远程仓库：

```bash
git remote -v
```

---

## 6. 代码规范

提交代码时，请尽量保持与项目现有代码风格一致。

基本要求：
* vibe coding 必须严格遵守 `AGENT.md` 中的代码规范。
* 使用 Kotlin 13.0.0 或更高版本
* 使用清晰、有意义的变量名
* 避免无意义缩写
* 避免重复代码
* 不提交明显无关的代码修改
* 不随意格式化整个项目
* 删除无用代码和调试代码
* 不提交敏感信息
* 对复杂逻辑适当添加注释

---

## 7. Commit 规范

建议每个 Commit 只完成一类修改。

推荐使用以下格式：

```text
类型: 简短描述
```

例如：

```text
feat: 添加游戏收藏功能
fix: 修复游戏库无法上拉加载的问题
refactor: 重构游戏扫描逻辑
docs: 更新 README
style: 优化游戏卡片布局
perf: 优化游戏列表加载性能
chore: 更新项目依赖
```

---

## 8. 提交代码

完成修改后：

```bash
git add .
```

提交：

```bash
git commit -m "feat: 添加游戏收藏功能"
```

推送到自己的仓库：

```bash
git push origin feature/game-favorite
```

然后在 GitHub 上创建 Pull Request。

---

## 9. Pull Request 规范

创建 Pull Request 时，请尽量提供清晰的说明。

推荐格式：

```markdown
## 修改内容

简单说明本次 PR 做了什么。

## 修改原因

为什么需要进行这个修改。

## 主要改动

- 修改 xxx
- 新增 xxx
- 修复 xxx

## 测试情况

- [x] 已完成本地测试
- [x] 原有功能正常
- [ ] 已在多个设备测试

## 相关 Issue

Closes #123

## 截图

如果涉及 UI 修改，请附上修改前后的截图。
```

不接受一个 PR 同时包含大量互不相关的功能与修改，审核难度大且不明确。
大批量代码建议先创建 Issue 进行讨论。务必确认功能是否符合项目方向。
如果功能符合项目方向，再创建 PR。

---

## 10. 功能 修改与添加

如果 Pull Request 涉及功能修改或添加，建议提供：

* 修改前与修改后的对比报告/新增功能的详细说明
* 详细修改思路与说明/新增功能的详细说明
* 解决或是新增的功能的适用以及问题的解决
* 直观的实机测试截图与对比，图片无法准确直观请附上视频链接

请尽量确保修改与添加不会破坏其他功能的完整性与准确性。

---

## 10. UI 修改

如果 Pull Request 涉及界面修改，建议提供：

* 修改前截图
* 修改后截图
* 手机界面截图
* 平板界面截图（如果适用）
* 横屏截图（如果适用）
* 深色模式截图（如果适用）

请尽量确保修改不会破坏其他屏幕尺寸下的布局以及符合UI规范。

---

## 11. 引擎与底层 修改

如果 Pull Request 涉及引擎修改或底层修改，建议提供：

* 实际优化效果与预期对比详细报告
* 附上真机测试视频链接或者可直观的截图
* 详细的改动思路与说明
* 进行小范围实际使用测试
* 可能会误报的情况下标注好相关代码段与说明


请务必确保修改不会破坏引擎与底层运作的正常与完整性。

---

## 11. Bug 修复

修复 Bug 时，请尽量说明：

```text
问题原因：
xxx

修复方式：
xxx

影响范围：
xxx

测试结果：
xxx
```

如果存在对应 Issue，可以在 Pull Request 中写：

```text
Fixes #123
```

或：

```text
Closes #123
```

Pull Request 合并后，对应 Issue 会自动关闭。

---

## 12. 新功能

较大的新功能建议先创建 Issue 进行讨论。

这样可以提前确认：

* 功能是否符合项目方向
* 是否已经有人实现
* 是否存在更合适的实现方式
* 是否需要调整架构
* 是否会影响已有功能

避免完成大量开发后才发现功能无法合并。

---

## 13. Pull Request 审核

提交 PR 后，等待机器人提出修改建议，根据建议进行修改。
如果有异议请对机器人具体代码误报进行单独回复说明
不要在一条说明里解释多条问题，每个问题都单独回复。

例如：

* 修改代码结构
* 调整命名
* 修复兼容性问题
* 增加异常处理
* 补充文档
* 修复 UI 问题

你可以继续向原分支提交 Commit。

Pull Request 会自动更新，无需重新创建 PR。

---

## 14. 合并要求

Pull Request 在合并前应尽量满足：

* 项目能够正常编译
* 没有明显运行时错误
* 没有破坏已有功能
* 没有提交敏感信息
* 没有大量无关文件修改
* Commit 信息基本清晰
* 新增代码符合项目整体风格
* UI 修改不存在明显适配问题

是否最终合并由项目维护者根据实际情况决定。

---

## 15. 行为准则

参与项目讨论时，请保持友好和尊重。

请避免：

* 人身攻击
* 恶意嘲讽
* 无意义争论
* Spam
* 发布与项目无关的内容
* 恶意提交 Issue 或 Pull Request

技术观点不同很正常，请尽量围绕代码和问题本身进行讨论。

---

## 16. 第一次参与开源？

如果这是你第一次提交 Pull Request，也完全没有问题。

基本流程其实很简单：

```text
Fork 项目
   ↓
Clone 到本地
   ↓
创建新分支
   ↓
修改代码
   ↓
Commit
   ↓
Push
   ↓
创建 Pull Request
```

如果你的实现还有不足，也可以先提交 PR，再根据 Review 意见继续修改。

---

## 感谢贡献 ❤️

感谢所有参与本项目开发、测试、反馈和文档维护的贡献者。

每一个 Issue、Pull Request 和建议，都能够帮助项目变得更好。

欢迎参与贡献！