Tips

You only need to read this page if you want to take part in the development of M9A! Users should refer to the M9A User Manual. For developing MaaFramework or your own projects, please visit MaaXYZ/MaaFramework.

A Brief Overview of the GitHub Pull Request Process

I don't know programming and just want to make small changes to JSON files/documents. What should I do?

Check out the GitHub Pull Request Guide for Beginners.

I have programming experience but haven't participated in related projects. What should I do?

1. If you forked the repository a long time ago, go to Settings in your repository, scroll to the bottom, and delete it.

2. Open the M9A Main Repository, click Fork, and then click Create fork.

3. Clone your own repository locally and pull the submodules:

   git clone --recursive https://github.com/<your-username>/M9A.git

   Warning

   Do not forget --recursive! Do not forget --recursive! Do not forget --recursive!
   OCR failures are often caused by forgetting to include --recursive.

   If you already cloned but find resources missing, run:

   git submodule update --init --recursive

4. Download the Release Package of MaaFramework and extract it into the deps folder.

   Tips

   This step can now be skipped and only needs to be performed when local testing of the command-line version is required.

5. Set up the development environment:

   • Install python(≥3.11)

   • Download and install VSCode.

   • Optionally install debugging/development tools:

     Tool	Description
     MaaDebugger	Standalone debugging tool
     Maa Pipeline Support	VSCode plugin for debugging, screenshots, ROI extraction, color picking, etc.
     MFAToolsPlus	Cross-platform toolbox providing convenient data acquisition and simulation testing methods
     ImageCropper(Not recommended)	Standalone tool for screenshots and ROI extraction
     MaaLogAnalyzer	Visual analysis of logs from MaaFramework-based applications

   Tips

   It is recommended to use the VSCode plugin for development and debugging, and MaaLogAnalyzer for user log analysis.

6. Start developing:

   Run python ./tools/ci/configure.py in the root directory of the project to configure the OCR model.

   Develop the M9A with the debugging/development tools installed in the previous step. The virtual environment will be automatically created in the .venv directory.

   Enjoy coding! Before starting, check out other parts.

7. Git operations:

   The most commonly used basic commands are:

   • git add <file>: Add files to the staging area. Use * to represent all files.
   • git commit -m "message": Commit the staged files to the local repository. Please follow the Conventional Commits Specification for clear commit messages.
   • git pull origin <branch>: Pull updates from the remote repository to the local repository.
   • git push origin <branch>: Push local changes to the remote repository.

   Warning

   During development, remember to commit changes regularly with a message. If you're not familiar with Git, you may need to create and switch to a new branch instead of committing directly to main. This way, your commits will grow on the new branch without being affected by updates to main.

   git checkout -b <branch-name> # Create and switch to a new branch

   After development, push your modified local branch to the remote repository (your fork):

   git push origin <branch-name>

   If there are changes in the M9A repository (e.g., commits from others), you may need to sync these changes to your branch:

   1. Link the original M9A repository:

      git remote add upstream https://github.com/MAA1999/M9A.git

   2. Fetch updates from the remote repository:

      git fetch upstream

   3. Rebase (recommended) or merge the changes:

      git rebase upstream/main # Rebase for a cleaner commit history. Rebase is recommended over merge when completing your personal PR.

      Or:

      git merge upstream/main

   Git reference materials:

   • Git Official Documentation
   • Git Simplified Guide
   • Git Tutorial | Runoob

8. Submit a Pull Request:

   Your modified code has been committed to your repository. Now, you need to submit a Pull Request to the M9A repository and wait for the maintainers to review it.

   GitHub Pull Request Reference