diff --git a/docs/en-us/develop/development.md b/docs/en-us/develop/development.md index b7bdb4c673..97395ff0a2 100644 --- a/docs/en-us/develop/development.md +++ b/docs/en-us/develop/development.md @@ -5,11 +5,15 @@ icon: iconoir:developer # Getting Started with Development -## Introduction to GitHub Pull Request flow +::: tip +This page mainly describes the PR workflow and MAA's file formatting requirements. If you want to learn specifically how to make changes to MAA's operational logic, please refer to the [Protocol Documentation](../protocol/) +::: + +## Introduction to GitHub Pull Request Flow ### I don't know programming but just want to modify some JSON files/documents, how can I do it? -Welcome to the [GitHub Pull Request Tutorial](./pr-tutorial.md) that anyone can understand (purely web-based on Github.com) +Welcome to the [Web-based PR Tutorial](./pr-tutorial.md) that anyone can understand (purely web-based on Github.com) ### I can program, but I've never used GitHub/C++/..., how do I get started? @@ -27,7 +31,7 @@ Welcome to the [GitHub Pull Request Tutorial](./pr-tutorial.md) that anyone can 4. Download prebuilt third-party libraries **Python environment required - search for Python installation tutorials if needed** - _（maadeps-download.py is located in the project root）_ + _(maadeps-download.py is located in the project root)_ ```cmd python maadeps-download.py @@ -41,11 +45,11 @@ Welcome to the [GitHub Pull Request Tutorial](./pr-tutorial.md) that anyone can 7. Configure Visual Studio settings - Select `RelWithDebInfo` and `x64` in the top configuration bar (Skip for Release builds or ARM platforms) - - Right-click `MaaWpfGui` -> Properties -> Debug -> Enable native debugging (This enables breakpoints in C++ Core) + - Right-click `MaaWpfGui` → Properties → Debug → Enable native debugging (This enables breakpoints in C++ Core) 8. Now you're ready to happily ~~mess around~~ start developing! 9. Commit regularly with meaningful messages during development - Beginners should create a new branch instead of committing directly to `dev`: + If you're not familiar with git usage, you might want to create a new branch for changes instead of committing directly to `dev`: ```bash git branch your_own_branch @@ -75,16 +79,16 @@ Welcome to the [GitHub Pull Request Tutorial](./pr-tutorial.md) that anyone can git fetch upstream ``` - 3. Rebase or merge: + 3. Rebase (recommended) or merge: ```bash - git rebase upstream/dev + git rebase upstream/dev # rebase ``` or ```bash - git merge + git merge # merge ``` 4. Repeat steps 7, 8, 9, 10. @@ -93,15 +97,15 @@ Welcome to the [GitHub Pull Request Tutorial](./pr-tutorial.md) that anyone can After opening Visual Studio, Git operations can be performed using VS's built-in "Git Changes" instead of command-line tools. ::: -## MAA file formatting requirements +## MAA File Formatting Requirements MAA uses a series of formatting tools to ensure that the code and resource files in the repository are visually unified for easy maintenance and reading. -Please ensure that it has been formatted before submission, or [enable Pre commit Hooks for automatic formatting](#use-pre-commit-hooks-to-automatically-format-code). +Please ensure that it has been formatted before submission, or [enable Pre-commit Hooks for automatic formatting](#use-pre-commit-hooks-to-automatically-format-code). The currently enabled formatting tools are as follows: -|File Type | Format Tool| +| File Type | Format Tool | | --- | --- | | C++ | [clang-format](https://clang.llvm.org/docs/ClangFormat.html) | | Json/Yaml | [Prettier](https://prettier.io/) | diff --git a/docs/en-us/develop/issue-bot-usage.md b/docs/en-us/develop/issue-bot-usage.md index 3f0949c092..51f2cad508 100644 --- a/docs/en-us/develop/issue-bot-usage.md +++ b/docs/en-us/develop/issue-bot-usage.md @@ -7,7 +7,9 @@ icon: bxs:bot The action of Issue Bot is [issue-checker](https://github.com/zzyyyl/issue-checker), with configuration file [issue-checker.yml](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/.github/issue-checker.yml). -**Note that your merge request will be marked as `ambiguous` when you are not committing with Commitizen specification.** +::: warning +Your pull request will be marked as `ambiguous` when you are not committing with Conventional Commits specification. +::: ## Features @@ -27,7 +29,7 @@ The action of Issue Bot is [issue-checker](https://github.com/zzyyyl/issue-check Issue Bot will check the title of your pull request. Unless the title starts with one of the following keywords, the pull request will be marked as `ambiguous`. - `build` `chore` `ci` `doc` `docs` `feat` `fix` `perf` `refactor` `rfc` `style` `test` -- `Merge` `merge` `Revert` `revert` +- `Merge` `merge` `Revert` `revert` `Reapply` `reapply` ### Triggering Manually @@ -52,7 +54,9 @@ It is better to trigger Issue Bot with keywords instead of commands listed below - `Duplicate of #{ISSUE_NUMBER}` will add `duplicate` label to the issue. - **You can add some `skip` operations if your comment may confuse Issue Bot.** -_Note1: The `COMMIT_HASH` here is the full 40-character hash._ +::: info Note +1 The `COMMIT_HASH` here needs to be the full 40 characters +::: #### Push diff --git a/docs/en-us/develop/linux-tutorial.md b/docs/en-us/develop/linux-tutorial.md index 47c2ee1b47..e9c1d7fd99 100644 --- a/docs/en-us/develop/linux-tutorial.md +++ b/docs/en-us/develop/linux-tutorial.md @@ -3,24 +3,27 @@ order: 2 icon: teenyicons:linux-alt-solid --- -# Linux Compiling Tutorial +# Linux Compilation Tutorial -**The tutorial requires some basic knowledge about Linux OS!** -If you just want to install MAA directly instead of compiling it yourself, please read [Emulator Support for Linux](../manual/device/linux.md). +**This tutorial requires readers to have some Linux environment configuration ability and programming foundation!** If you only want to directly install MAA instead of compiling it yourself, please read [User Manual - Linux Emulators and Containers](../manual/device/linux.md). ::: info Note -Linux build of MAA is still under discussion, some of the content might be outdated, please follow the script in [GitHub workflow file](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/.github/workflows/ci.yml#L134), also reference [AUR PKGBUILD](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=maa-assistant-arknights), [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-assistant-arknights/package.nix) +MAA's build method is still under discussion. The content of this tutorial may be outdated. Please refer to the scripts in [GitHub workflow file](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/.github/workflows/ci.yml#L134). You can also refer to [AUR PKGBUILD](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=maa-assistant-arknights), [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-assistant-arknights/package.nix). ::: -## Compiling MAA +::: info +Mac can use the `tools/build_macos_universal.zsh` script for compilation. It's recommended to refer to the README.md of the [MaaAssistantArknights/MaaMacGui](https://github.com/MaaAssistantArknights/MaaMacGui) project. +::: -1. Download build depends +## Compilation Process + +1. Download compilation dependencies - Ubuntu/Debian - ```bash - sudo apt install gcc-12 g++-12 cmake zlib1g-dev - ``` + ```bash + sudo apt install gcc-12 g++-12 cmake zlib1g-dev + ``` - Arch Linux @@ -28,30 +31,30 @@ Linux build of MAA is still under discussion, some of the content might be outda sudo pacman -S --needed gcc cmake zlib ``` -2. Build or download third-party libraries +2. Build third-party libraries - You may either download pre-built dependencies or build them from scratch + You can choose to download pre-built dependency libraries or compile from scratch - - Download pre-built libraries (recommended) + - Download pre-built third-party libraries (recommended) > **Note** - > It contains shared objects built on a relatively new linux distro (Ubuntu 22.04), which may cause ABI incompatibility if you are working on a system with older version of libstdc++. + > Contains dynamic libraries compiled on relatively new Linux distributions (Ubuntu 22.04). If your system's libstdc++ version is older, you may encounter ABI incompatibility issues. ```bash python maadeps-download.py ``` - If this does not work for you due to ABI issue, and containerization is not an option, you may build them from scratch + If you find the libraries downloaded above cannot run on your system due to ABI version issues and you don't want to use container solutions, you can also try compiling from scratch - - Build from source + - Build third-party libraries from scratch (will take considerable time) ```bash git submodule update --init --recursive cd MaaDeps - python build.py + python build.py ``` -3. Build MAA +3. Compile MAA ```bash CC=gcc-12 CXX=g++-12 cmake -B build \ @@ -61,24 +64,26 @@ Linux build of MAA is still under discussion, some of the content might be outda cmake --build build ``` - To install MAA to the target location, note that MAA is recommended to run by specifying `LD_LIBRARY_PATH`, do not use administrator privileges to load MAA into `/` + To install MAA to target location, note that MAA is recommended to run by specifying `LD_LIBRARY_PATH`, don't use administrator privileges to install MAA into `/usr` ```bash cmake --install build --prefix ``` -## Integration +## Integration Documentation -[~~Maybe not a doc~~](../protocol/integration.md) +[~~Perhaps not really documentation~~](../protocol/integration.md) ### Python -Refer to the implementation of `__main__` in [Python demo](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/Python/sample.py) +You can refer to the implementation of `__main__` in [Python demo](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/Python/sample.py) -### C +### C++ -Refer to the implementation of [CppSample](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/Cpp/main.cpp) +You can refer to the implementation in [CppSample](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/Cpp/main.cpp) ### C Sharp -Refer to the implementation of [MaaWpfGui](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/MaaWpfGui/Main/AsstProxy.cs) + + +You can refer to the implementation in [MaaWpfGui](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/MaaWpfGui/Main/AsstProxy.cs) diff --git a/docs/en-us/develop/overseas-client-adaptation.md b/docs/en-us/develop/overseas-client-adaptation.md index fb16d21f22..69d9dc2134 100644 --- a/docs/en-us/develop/overseas-client-adaptation.md +++ b/docs/en-us/develop/overseas-client-adaptation.md @@ -3,114 +3,116 @@ order: 5 icon: ri:earth-fill --- -# Overseas Clients Adaptation +# Overseas Client Adaptation Tutorial ## Preparation Before starting this tutorial, make sure you have: -1. Installed and properly configured the required software. There should be information in the `readme.md` of the ZH-CN client or the corresponding client to ensure that the supported features work properly. -2. Read [Task Schema](../protocol/task-schema.md) and have a basic understanding of the meaning and usage of each field. You should also understand the meaning and usage of `@` and `#` in the code. -3. Understand that the `task.json` file and template image of the ZH-CN client will be used as alternatives when they are unmentioned or missing for the overseas client. The content in the `task.json` for the overseas client should be rewritten according to the fields of the ZH-CN task. -4. Have some English ability, be able to read English logs, and be able to find missing pictures and other information through the logs. -5. Understand that it is recommended to perform the modification individually according to the task chain. For example, to modify the Award task, you should modify the `template image`, `text`, and `roi` step by step in accordance with the order in its `next` field. This will ensure that every task is working normally after modification and errors can be easily spotted. Additionally, this can prevent confusion and forgetting which task the software is stuck on when too much content is modified at once. +1. Installed and properly configured the required software. There should be relevant information in the CN client or corresponding client's `readme.md` to ensure that supported features work properly. +2. Read the [Task Schema](../protocol/task-schema.md) and have a basic understanding of the meaning and usage of each field, and understand the meaning and usage of `@` and `#` type tasks. +3. Understand that content not mentioned or missing in overseas client `task.json` and template images will use CN client `task.json` and template images as fallbacks. Content in overseas client `task.json` will override and rewrite corresponding fields of CN client tasks. +4. Have sufficient English ability to read English logs and find missing images and other information through logs. +5. It's recommended to modify according to task chains. For example, for the `Award` task, gradually replace `template images` / `text` / `modify roi` step by step according to the `next` order of the `Award` task in CN client `task.json`, ensuring each step works properly after modification or can quickly identify errors. This avoids confusion about which step the program is stuck on when too many changes are made at once. -### Preparation before making changes +### Pre-modification Preparation -Before making changes, there are several preparations that need to be noted: +Before making modifications, there are several preparation steps to note: -1. Refer to the ZH-CN client's `task.json` and make sure you have prepared the template images and text content for the overseas client. -2. Make sure you have ready access to these images and text content. +1. Refer to CN client task.json and ensure you have prepared template images and text content for overseas clients that differ from CN client. +2. Ensure you can access these images and text content at any time. -## Get screenshots +## Getting Screenshots To get high-quality screenshots, please follow these guidelines: -1. Use the screenshot tool provided with the emulator to take and save screenshots. -2. Ensure that the size of the screenshot is at least `1280x720` and the aspect ratio is `16:9`. -3. Make sure the screenshot does not contain any extraneous content, such as the taskbar, status bar, or notification bar. -4. Make sure the screenshot includes all the content that needs to be recognized. +1. Use the emulator's built-in screenshot tool to take and save screenshots. +2. Ensure screenshot dimensions are larger than `1280*720` with aspect ratio `16:9`. +3. Ensure screenshots don't contain any irrelevant content, such as taskbar, status bar, notification bar, etc. +4. Ensure screenshots contain all content that needs to be recognized. -To crop the image and get the text/image region of interest (ROI), you will need to install `Python` and `OpenCV`, and download the `MaaAssistantArknights/tools/CropRoi/main.py` file. +To crop images and get text/image `roi`, you need to install `python` and `opencv`, and download the `MaaAssistantArknights/tools/CropRoi/main.py` file. -Then, follow these steps: +Then follow these steps: 1. Create new `src` and `dst` folders in the same directory as `main.py`. -2. Place the **complete screenshot** of the text/image that needs to be resized or in need of a new ROI value into the `src` folder. +2. Place **complete screenshots** that need resizing or text/image `roi` extraction into the `src` folder. 3. Run `main.py`. -4. Select the target range by dragging the mouse, making sure not to include extraneous content. -5. Once the range is determined, press `S` to save and `Q` to exit. The cropped image will be saved in the dst folder. +4. Use mouse drag to select target range, try not to include irrelevant content. +5. After determining the range, press `S` to save, press `Q` to exit. Cropped images will be saved in the `dst` folder. -For example, the output after completing a crop would be: +For example, output after completing one crop: -``` log +```log src: Screenshot_xxx.png dst: Screenshot_xxx.png_426,272,177,201.png original roi: 476, 322, 77, 101, amplified roi: 426, 272, 177, 201 ``` -In this example, `Screenshot_xxx.png` is the name of the full screenshot placed in the `src` folder, and `Screenshot_xxx.png_426,272,177,201.png` is the name of the cropped image. +Where: -The `original roi` is the area selected by the mouse, while the `amplified roi` is the enlarged area. You will need the enlarged area, so you should use the `amplified roi` value to fill in the roi field in task.json. +`Screenshot_xxx.png` is the name of the complete screenshot placed in the `src` folder. `Screenshot_xxx.png_426,272,177,201.png` is the cropped image. -## Modify the template image +`original roi` is the mouse-selected area. `amplified roi` is the enlarged area. You need the enlarged range, so fill the `roi` field in `task.json` with this value. -Before modifying the template image, you need to open the template image folder of the corresponding client and the template image folder of the ZH-CN client. +## Modifying Template Images + +Before modifying template images, you need to open the corresponding client's template image folder and CN client's template image folder. For example: -- The location of the template image folder for EN client is `MaaAssistantArknights\resource\global\YoStarEN\resource\template`. -- The location of the template image folder for the ZH-CN client is `MaaAssistantArknights\resource\template`. +- EN client template image folder location: `MaaAssistantArknights\resource\global\YoStarEN\resource\template`. +- CN client template image folder location: `MaaAssistantArknights\resource\template`. -Refer to the template images mentioned in the `task.json` file, compare the template images of the ZH-CN client and the overseas client, and identify any missing templates in the overseas client. +Refer to template images mentioned in `task.json`, compare CN client and overseas client template images, and find templates missing in overseas client. -Typically, template images containing text need to be replaced with screenshots, with the exception of images such as logos. If the size of the image is significantly larger than the corresponding template image in the ZH-CN client, you may need to modify the size of the `roi`. +Usually, except for logos and other images, templates containing text need to be replaced through screenshots. If image dimensions are significantly larger than corresponding CN client template images, you need to modify `roi` size. -Once you have captured and renamed the template image, you can place it in the template image folder of the corresponding client. +Place captured and renamed template images into the corresponding client's template image folder. -## Modify the text content +## Modifying Text Content -Before modifying the text content, you will need to open the `task.json` file for both the corresponding server and ZH-CN client. +Before modifying text content, you need to open the corresponding server's `task.json` and CN client's `task.json`. For example: -- The location of `task.json` in EN client is `MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json`. -- The location of `task.json` for ZH-CN client is `MaaAssistantArknights\resource\tasks.json`. +- EN client `task.json` location: `MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json`. +- CN client `task.json` location: `MaaAssistantArknights\resource\tasks.json`. -To modify the text, locate the corresponding task and change the `text` field to the content displayed in the corresponding server. Keep in mind that the identified content can be a substring of the full content within the game. In general, you should replace any `text` containing text unless it is recognized as a pure ASCII character. +Find the corresponding task and modify the `text` field to content displayed in the corresponding server. Note that recognized content can be a substring of complete in-game content. -If the text length is significantly longer than the ZH-CN client version, you may need to modify the size of the `roi` field. For example, if the difference in length between the `"任务"`(Mission in chinese) and the English word `"Mission"` is too large, you may need to modify the size of the `roi` for that mission in the overseas client. +Usually, unless it's pure ASCII character recognition, `text` containing text needs to be replaced. If text length is significantly larger than CN client, you need to modify `roi` size, such as the length difference between `"任务"` and `"Mission"` being too large, requiring modification of overseas client task `roi` size. -If the task does not exist in the `task.json` file of the corresponding overseas server, you will need to add it. Simply fill in the `text` field with the appropriate content. +If the corresponding overseas client `task.json` doesn't have the task, you need to add the task, only filling in the `text` field. -## Modify ROI range +## Modifying ROI Range -To modify the ROI range: +1. Open the corresponding server's `task.json`, such as EN client location `MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json` +2. Find the corresponding task that needs `roi` range modification, use your prepared overseas game interface screenshots, and adjust `roi` range size according to `amplified roi`. +3. Usually, `roi` doesn't need modification, only when recognition content size difference with CN client is too large. +4. If the corresponding overseas client `task.json` doesn't have the task, add the task and write the `roi` field. -1. Open the `task.json` file for the corresponding server, for example, the location of the EN client's `task.json` file is `MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json`. -2. Find the task that corresponds to the ROI range you need to modify, and use a screenshot of the overseas game interface to adjust the size of the `roi` range according to the amplified ROI. -3. Normally, you should not need to modify the `roi` range, but you may need to do so if the difference in size between the text and the Chinese client version is too large. -4. If the task does not exist in the `task.json` file of the corresponding overseas client, add the task and write the `roi` field with the appropriate values. +## Save Settings and Restart Software -## Save the settings and restart the software +After modifications are complete, restart the software to reload files and make changes effective. Or create a `DEBUG.txt` file in the software directory before opening the software, so templates and files reload every time you click start, without needing restart. -After making the changes, you will need to save the settings and restart the software in order for the changes to take effect. To do this, you can either restart the software and reload the file, or create a new `DEBUG.txt` file in the software directory. This will cause the template and files to be reloaded every time you click the "Link Start" button, so you will not need to restart the software. +Check for success: -To check for success: +1. Check software operation to ensure it works normally on overseas clients. +2. If it doesn't work properly, check if modifications are correct or view log output to find error locations. -1. Test the operation of the software to ensure that it is functioning properly on the overseas server. -2. If it is not working properly, you will need to check if the changes are correct, or check the log output to determine what went wrong. +## Reading Logs -## Interpreting the logs +Sometimes after modifying `task.json`, we find the program still can't run correctly. In this case, we should check logs to find error locations and modify corresponding tasks. -If you have modified the `task.json` file but the program is still not functioning correctly, it may be helpful to check the logs to find any errors and modify the corresponding task accordingly. The log file is typically located in the root directory of the software, and is named `asst.log`. If you compiled MAA yourself, it may be located in the `\x64\Release` or `\x64\RelWithDebInfo` directory, depending on the compilation mode you selected when compiling. +Log file location is in the software root directory, filename `asst.log`. If you compiled MAA yourself, it's in `\x64\Release` or `x64\RelWithDebInfo`, depending on your compilation mode selection. -Interpreting the logs can be helpful in identifying any issues with the program. Here is an example log: +Here's a log example: -``` log +```log [2022-12-18 17:43:17.535][INF][Px7ec][Tx15c8] {"taskchain":"Award","details":{"to_be_recognized":["Award@ReturnTo","Award","ReceiveAward","DailyTask","WeeklyTask","Award@CloseAnno","Award@CloseAnnoTexas","Award@TodaysSupplies","Award@FromStageSN"],"cur_retry":10,"retry_times":20},"first":["AwardBegin"],"taskid":2,"class":"asst::ProcessTask","subtask":"ProcessTask","pre_task":"AwardBegin"} -[2022-12-18 17:43:18.398][INF][Px7ec][Tx15c8] Call ` C:\Program Files\BlueStacks_nxt\. \HD-Adb.exe -s 127.0.0.1:5555 exec-out "screencap | gzip -1" ` ret 0 , cost 862 ms , stdout size: 2074904 , socket size: 0 +[2022-12-18 17:43:18.398][INF][Px7ec][Tx15c8] Call ` C:\Program Files\BlueStacks_nxt\.\HD-Adb.exe -s 127.0.0.1:5555 exec-out "screencap | gzip -1" ` ret 0 , cost 862 ms , stdout size: 2074904 , socket size: 0 [2022-12-18 17:43:18.541][TRC][Px7ec][Tx15c8] OcrPack::recognize | roi: [ 500, 50, 300, 150 ] [2022-12-18 17:43:18.541][TRC][Px7ec][Tx15c8] Ocr Pipeline with asst::WordOcr | enter [2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] Ocr Pipeline with asst::WordOcr | leave, 93 ms @@ -122,20 +124,21 @@ Interpreting the logs can be helpful in identifying any issues with the program. [2022-12-18 17:43:19.144][TRC][Px7ec][Tx15c8] asst::ProcessTask::_run | enter ``` -In this log, you can see that: +In this log, you can see: -- `"taskchain"` represents the task currently in progress. -- `"details"` is the content of the task, including the fields to be recognized (`to_be_recognized`) and the current number of retries (`cur_retry`) and the total number of retries (`retry_times`). -- `"first"` represents the start of the task. -- `"taskid"` is the task number. -- `"class"` and `subtask` represent the class and subtask of the task, respectively. -- `"pre_task"` represents the previous task. -In addition, the execution of the command (e.g. `Call`) and the `OCR` information (e.g. `OcrPack::recognize`) are recorded in the log. +- `taskchain` represents the currently running task. +- `details` is task content, including fields to be recognized (`to_be_recognized`), current retry count (`cur_retry`), and total retry count (`retry_times`). +- `first` represents task start. +- `taskid` is the task number. +- `class` and `subtask` represent task class and subtask respectively. +- `pre_task` represents the previous task. -For example, in this log, `"to_be_recognized"`,`"cur_retry":3,"retry_times":20` means that the task has been attempted to be recognized 10 times, and the maximum number of times is 20. After the maximum number of times is reached, the task will be skipped and an error will be reported, and the next task will be performed. If there are no issues with the previous task, it is likely that there is a problem with the recognition here. To troubleshoot this issue, you can check the tasks mentioned in the log to see if there is a corresponding template file, if the `text` field of the corresponding task is incorrect, or if the `roi` range for task recognition is incorrect, and make any necessary modifications. +Additionally, the log records command execution (like `Call`) and `OCR` information (like `OcrPack::recognize`). -By looking at the corresponding template image, you may find that there is a template for this image in the EN client template folder, but the size is larger than the image in template folder for the ZH-CN client . This could cause the `roi` in ZH-CN client to not be recognized in the EN client, so you may need to modify the corresponding task's `roi` in the EN client's `task.json` file to match the size of the image in the EN client. +In this log, `"to_be_recognized"`, `"cur_retry":3,"retry_times":20` indicates it has repeatedly tried recognition 3 times, with maximum recognition attempts of 20. After reaching maximum attempts, it will skip the task and report error, continuing to the next task. If previous tasks had no issues, we can basically determine there's a recognition problem here. We need to check tasks mentioned in the log to see if there's a corresponding `template file`, if the corresponding task's `text` is incorrect, if task recognition `roi` range is correct, to find and fix the problem. -## Submit your changes +By checking the corresponding template image, we found there's a template for this image in the EN client template folder, but it's significantly larger than the CN client image, causing CN client's `roi` to fail recognition on EN client. So we need to modify the corresponding task `roi` in EN client's `task.json` to match EN client image size. -Check out [Github Pull Request Guide](./pr-tutorial.md) +## Submit Your Changes + +Please refer to [GitHub Pull Request Guide](./pr-tutorial.md) diff --git a/docs/en-us/develop/pr-tutorial.md b/docs/en-us/develop/pr-tutorial.md index 1e6cfabf4f..acac62171e 100644 --- a/docs/en-us/develop/pr-tutorial.md +++ b/docs/en-us/develop/pr-tutorial.md @@ -3,24 +3,24 @@ order: 3 icon: mingcute:git-pull-request-fill --- -# GitHub Pull Request User Guide +# Web-based PR Tutorial -This document is machine-translated. If you have the ability, please refer to the Chinese version. We would greatly appreciate any errors or suggestions for improvement. +A GitHub Pull Request guide that even beginners can understand (\*´▽ ｀)ノノ ::: warning -Many concepts in this tutorial have been simplified in order to make it more accessible to a wider audience, even at the expense of some elegance and accuracy. -For those who have experience using Git and programming knowledge, you may refer to the more advanced tutorial in [Development](./development.md) +This tutorial simplifies many concepts to make them accessible to more people. It includes some ~~inelegant but simple~~ operations and not entirely accurate explanations. Please go easy on us, experts. +If you have some git experience and programming background, ~~then why are you reading this~~, you can check out the more advanced tutorial [GitHub Pull Request Process Overview](./development.md) ::: -## Basic concepts and terminology +## Basic Concepts and Terminology -This chapter contains slightly dry content. If you're not interested, you can skip directly to the practical section below. If there is anything you don't understand, you can come back to read this chapter later. +This section might be a bit dry. Feel free to skip to the practical section below and come back here if you need clarification. ### Repository -"Repo" is short for "repository", which is the place where we store our code and other resource files. +Abbreviated as "repo", the place where we store our code and other resource files. -👇 You can think of the current web page and all of its contents as the repository for MAA (we usually refer to it as MAA's main repository). +👇 You can simply understand this webpage and all its contents as MAA's repository (we generally call it MAA's main repository) ```component Image1 { @@ -35,11 +35,12 @@ This chapter contains slightly dry content. If you're not interested, you can sk ### Fork -To fork, literally meaning to make a copy of MAA's code, and then perform subsequent modifications and operations to avoid damaging the original repository. +Literally means to copy. Fork a copy of MAA's code so you can make subsequent modifications without breaking the original. +Although "copy" in Chinese might first remind us of the "copy" operation, "fork" doesn't have a clear translation, so we usually use the English term directly, like "fork a copy of the code." -Since it's a copy, let's assume it's called `MAA (1)`. -To distinguish it from the original repository, we usually refer to the original MAA repository as "main repository" or "upstream". -Since everyone can make a copy of their own, the copied repository is called a "personal repository" or "origin". +Since it's a copy, it becomes `MAA (1)` (just kidding) +To distinguish from the original repository, we generally call the original MAA repository the "main repository" or "upstream repository." +Since everyone can fork their own copy, the copied version is called a "personal repository" or "origin repository." ```component Image1 { @@ -54,11 +55,12 @@ Since everyone can make a copy of their own, the copied repository is called a " ### Pull Request -Continuing from the previous section, after you have made changes to your forked personal repository, how do you provide the changes to the main repository? This is when you can open a pull request (PR) to request that your modified content be added to the main repository. +Abbreviated as PR. "Pull request" sounds strange when literally translated, ~~and it's too many characters to type~~, so everyone usually just says "make a PR." +Following the above, after you fork your personal repository and make modifications, how do you contribute your changes to the main repository? This is when you can open a PR to request that your modifications be added to the main repository. -Of course, since it's a "request", it naturally requires approval. MAA Team may provide feedback on your modifications, but our feedback may not necessarily be entirely correct. Let's have a reasonable discussion together~ +Of course, since it's a "request," it naturally needs approval. MAA Team members might provide feedback on your modifications, though our opinions aren't necessarily always correct - let's discuss reasonably~ -👇 The following are the PRs currently submitted by contributors and awaiting approval from MAA Team. +👇 Below are PRs currently submitted by contributors, waiting for approval ```component Image1 { @@ -73,12 +75,14 @@ Of course, since it's a "request", it naturally requires approval. MAA Team may ### Conflict -Assuming that there is a file called A in the main repository with the content 111. You forked a copy and changed its content to 222. However, just as you were about to submit the PR, another person named Zhangsan forked a copy and submitted a PR with changes to the A file, changing it to 333. -Now we have a conflict, as both of you have modified the A file but in different ways. This conflict can be difficult to resolve, and here we are only explaining the concept to help you understand what has happened when you encounter it, without going into the details of the solution. +Imagine there's a file A in the main repository with content "111." +You fork a copy and change its content to "222," but just as you're about to submit a PR, someone else also forks a copy, submits a PR, and changes file A to "333." +Now we see that both of you modified file A differently. Whose version should we listen to? This is a Conflict. +Conflicts are somewhat troublesome to resolve. This section only explains the concept to help you understand what's happening when you encounter one. -## Full Process of Pure Web-based PR Operation +## Complete Web-based PR Process -1. First, go to the MAA main repository and click the button in the top right corner to fork a copy of the code. +1. First, enter MAA's main repository and click the Fork button in the upper right corner to fork a copy of the code ```component Image1 { @@ -91,7 +95,7 @@ Now we have a conflict, as both of you have modified the A file but in different } ``` -2. Then, click on 'Create Fork' directly. +2. Then directly click "Create Fork" ```component Image1 { @@ -104,170 +108,49 @@ Now we have a conflict, as both of you have modified the A file but in different } ``` -3. You will be taken to your personal repository, which will have a title of "your_name/MaaAssistantArknights", with a small note below stating "forked from MaaAssistantArknights/MaaAssistantArknights" (copied from the MAA main repository). +3. You'll arrive at your personal repository. You can see the title is "YourName/MaaAssistantArknights" with small text below saying "forked from MaaAssistantArknights/MaaAssistantArknights" - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-3-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-3-dark.png" - } - ] - } - ``` +4. Find the file you want to modify. You can click "Go to file" for global search, or browse through the folders below if you know where the file is -4. Find the file you want to edit. You can click 'Go to file' to search globally, or you can browse through the folders below if you know where the file is located. +5. After opening the file, directly click the ✏️ in the upper right corner of the file to edit - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-4-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-4-dark.png" - } - ] - } - ``` +6. Start editing! (For resource files, we recommend testing modifications in your local MAA folder first, confirming they work before pasting into the webpage to avoid errors) -5. After opening the file, click on the ✏️ icon on the top right corner of the file to start editing. +7. After editing, click the button in the upper right corner to open the commit page and write what you changed - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-5-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-5-dark.png" - } - ] - } - ``` + We have a simple commit title [naming format](https://www.conventionalcommits.org/en/v1.0.0/). It's best to follow it, but if you really can't understand it, you can write something simple first. -6. Make your changes! (If it's a resource file, we recommend testing the changes in your local MAA folder before pasting them in the web page to avoid errors). -7. Once you've finished editing, click the button 👇 in the top right corner to open the commit page and write a brief description of what you changed. +8. Have a second file to modify? Discovered an error after finishing? No problem! Just repeat steps 4-7! - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-7-1-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-7-1-dark.png" - } - ] - } - ``` +9. After all modifications are complete, make a PR! Click "Code" to return to your **personal repository's** homepage + If there's a "Compare & Pull Request" button, that's great - click it directly! + If not, don't worry - click the "Contribute" button below, then "Open Pull Request" - it's the same thing. - We have a simple commit title [naming format](https://www.conventionalcommits.org/zh-hans/v1.0.0/), which you should try to follow. However, if you find it difficult to understand, you can just write something for now. +10. You'll arrive at the main repository's PR page. Please verify that what you want to PR is what you intend to submit. + As shown in the image, there's a leftward arrow in the middle, requesting to merge the right side's PersonalName/MAA dev branch into the main repository/MAA dev branch. + Scrolling down shows the differences between these two branches - what you've changed. - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-7-2-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-7-2-dark.png" - } - ] - } - ``` + Then write a title and specific content of your modifications, then click confirm. + PR titles also need to follow the [naming format](https://www.conventionalcommits.org/en/v1.0.0/). If you still can't understand it, you can write something simple first. -8. Need to edit another file? Made a mistake and want to change it again? No problem! Simply repeat steps 4-7 for the other file. -9. When all changes are made, create a Pull Request by going to the Pull Request tab in your personal repository. - If there is a "Compare & Pull Request" button, that's great, just click it! - If not, don't worry, clicking "Open Pull Request" below is also the same. +11. Wait for MAA Team members to review! They might also provide feedback + 👇 For example (purely for entertainment, don't take it seriously) - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-9-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-9-dark.png" - } - ] - } - ``` +12. If team members say to modify some small issues, return to **your personal repository** and repeat steps 4-7! + Note: you don't need to repeat steps 1-2 (re-fork) and steps 9-10 (re-Pull Request). Your current Pull Request is still pending review, and subsequent modifications will directly enter this Pull Request. + 👇 For example, you can see an additional modification entry at the bottom -10. Now you are in the main repository, please double-check the changes you want to PR. - As shown in the figure, there is a leftward arrow, which means you want to merge the dev branch from your forked repository "your_name/MAA" to the dev branch of the main repository "MAA". - Scrolling down shows the differences between these two branches, indicating what changes you have made. +13. Once team members approve, everything is complete! Your modifications have entered MAA's main repository! - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-10-1-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-10-1-dark.png" - } - ] - } - ``` +14. Next time you want to submit another PR, first return to your personal repository's homepage and click "Sync fork" to synchronize your repository with the main repository. + Note here: if there's a red "Discard 1 commit," click the red one; if not, then click the green "Update branch." + You can then repeat steps 4-10 to make modifications again. - Then, write a title and description of your changes, and click "Create Pull Request". - The PR title should also follow the [naming format](https://www.conventionalcommits.org/zh-hans/v1.0.0/). However, if you still don't understand it, you can also just write something for now. +**After version release**, your GitHub avatar will automatically be added to the contributors list. Thank you very much for your selfless contributions! +~~Why are they all anime characters? Oh wait, I am too, never mind then~~ - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-10-2-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-10-2-dark.png" - } - ] - } - ``` - -11. Just wait for the MAA Team members to review it! Of course, they may also provide some comments, - 👇 for example (for entertainment purposes only, do not take it seriously): - - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-11-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-11-dark.png" - } - ] - } - ``` - -12. If they request further changes, go back to **your personal repository** and repeat steps 4-7! - Note that you do not need to redo step 1-2 (re-fork) or step 9-10 (re-Pull Request), your current Pull Request is still pending review, and subsequent changes will be added directly to this Pull Request. - 👇 For example, you can see that "revised demo" has been added at the bottom. - - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-12-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-12-dark.png" - } - ] - } - ``` - -13. Once the experts approve the PR, you're all set! Your changes have been merged into the main MAA repository! - -14. If you want to submit another PR next time, please first go back to the homepage of your personal repository and click 'Sync fork' to synchronize your repository with the main repository. - Note here: If there is a red 'Discard 1 commit', click the red one. If there isn't, then click the green 'Update branch'. - Next, you can repeat steps 4-10 to make further modifications. - - ```component Image1 - { - "imageList": [ - { - "light": "images/zh-cn/pr-tutorial/pr-14-1-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-14-1-dark.png" - }, - { - "light": "images/zh-cn/pr-tutorial/pr-14-2-light.png", - "dark": "images/zh-cn/pr-tutorial/pr-14-2-dark.png" - } - ] - } - ``` - -**After the version is released**, your GitHub avatar will automatically be added to the contributors list. Thank you very much for your selfless dedication! -::: tip Contributors/Participators -Thank you to everyone involved in development and testing. Your help is going to ~~Make MAA Great Again~~! (\*´▽ ｀)ノノ +::: tip Contributors +Thanks to all friends who participated in development/testing. Everyone's help makes MAA better and better! (\*´▽ ｀)ノノ [![Contributors](https://contributors-img.web.app/image?repo=MaaAssistantArknights/MaaAssistantArknights&max=105&columns=15)](https://github.com/MaaAssistantArknights/MaaAssistantArknights/graphs/contributors) :::