MaaGumballs

开发前须知

[!NOTE]

只有当您想要开发 MaaGB 时才需要看当前页面！

用户请转到 MaaGB 使用手册。

开发 MaaFramework 或开发自己的项目请到 MaaXYZ/MaaFramework。

Github Pull Request 流程简述

我不懂编程，只是想改一点点 JSON 文件/文档等，要怎么操作？

欢迎收看牛牛也能看懂的 GitHub Pull Request 使用指南

我有编程经验，但是没参与过相关项目，要怎么做？

如果很久以前 fork 过，先在自己仓库的 Settings 里，翻到最下面，删除
打开 MaaGB 主仓库，点击 Fork，继续点击 Create fork
克隆你自己的仓库到本地，并拉取子模块
```
 git clone --recursive https://github.com/<你的用户名>/MaaGumballs.git
```
⚠

–recursive 一定不要忘！–recursive 一定不要忘！–recursive 一定不要忘！

OCR异常失败很可能就是没加recursive导致。子模块拉取失败会导致缺少必要的依赖文件。
下载 MaaFramework 的 Release 包，解压到 deps 文件夹中。

配置编程环境

下载并安装vscode

选择性安装调试/开发工具

工具	简介
MaaDebugger	独立调试工具
Maa Pipeline Support	VSCode 插件，提供调试、截图、获取 ROI 、取色等功能
MFA Tools	独立截图、获取 ROI 及取色工具
ImageCropper(不推荐)	独立截图及获取 ROI 工具

本地安装
1. 安装嵌入式python（仅Windows需要）
```
./tools/ci/setup_embed_python.ps1
```
2. 通过运行 install 组装部件
```
python ./tools/install.py
```
便可以在 install 文件夹运行 MaaGB 了。
开始开发

开始愉快的改代码吧，开始前查看相关阅读。
git 操作

通常用的最多的基本命令有：
- git add <file>：添加文件到暂存区，* 代表全部文件
- git commit -m "message"：提交暂存区到本地仓库。message 请遵循约定式提交规范，让你的 commit 信息更加清晰
- git pull origin <branch>：拉取远程仓库到本地仓库
- git push origin <branch>：推送本地仓库到远程仓库
⚠

开发过程中，每一定数量，记得提交一个 commit, 别忘了写上 message 假如你不熟悉 git 的使用，你可能需要创建并切换到一个新的分支，而不是直接提交在 main 上这样你的提交就能在新的分支上生长，不会受到 main 更新的打扰
```
 git checkout -b <branch-name> # 创建并切换到新的分支
```
完成开发后，推送你修改的本地分支到远程仓库（fork 的仓库）
```
 git push origin <branch-name>
```
当 MaaGB 仓库出现更改（如其他人的commit），你可能需要把这些更改同步到你的分支
1. 关联 MaaGB 原仓库：首次需要执行以下命令
```
 git remote add upstream https://github.com/KhazixW2/MaaGumballs.git`
```
2. 拉取远程仓库更新：
```
 git fetch upstream
```
3. 变基（推荐）或者合并修改：
```
 git rebase upstream/main # 变基，使commit历史更清晰，完成你的个人pr时建议使用rebase而不是merge来合并修改
```
  或者
```
 git merge upstream/main
```
git 参考资料：
- git 官方文档
- git 简明指南
- [git 教程菜鸟教程](https://www.runoob.com/git/git-tutorial.html)
提交 Pull Request

你修改的代码已经提交到你的仓库，现在你需要提交一个 Pull Request 到 MaaGB 的仓库，等待维护者审核

GitHub Pull Request 参考

MaaGB 格式化要求

MaaGB 使用一系列的格式化工具来保证仓库中的代码和资源文件美观统一，以便于维护和阅读

请确保在提交之前已经格式化, 目前VSCode自动触发JSON文件的格式化。

还需要手动下载并安装以下工具：MarkDownLint、BlackFormatter.这两个插件都可以在vscode插件市场中下载。

目前启用的格式化工具如下：

文件类型	格式化工具
JSON/VSCode	VSCode Settings
Markdown	MarkdownLint
Python	Black Formatter

MaaGumballs

开发前须知

Github Pull Request 流程简述

我不懂编程，只是想改一点点 JSON 文件/文档等，要怎么操作？

我有编程经验，但是没参与过相关项目，要怎么做？

MaaGB 格式化要求

相关阅读