Merge pull request #1907 from MaaAssistantArknights/docs/development

docs: 修改开发相关文档
2026-07-20 10:57:45 +08:00 · 2022-09-23 17:46:38 +08:00
parent 335d2f94de 891e3052ac
commit a1e231a4b4
3 changed files with 62 additions and 17 deletions
--- a/docs/2.2-开发相关.md
+++ b/docs/2.2-开发相关.md
@@ -17,15 +17,24 @@
 5. 双击打开 `MeoAssistantArknights.sln` 文件。Visual Studio 会自动加载整个项目。
 6. 测试一下是否成功搭建编程环境，选择参数 `Release`, `x64`, 右键 `MeoAsstGui` 设为启动项目；点击启动，选择继续调试。如果成功打开了 GUI，就说明成功搭建了环境。如果求稳，可以继续连接模拟器跑一下 MAA
 7. 到这里，你就可以愉快地 ~~瞎 JB 改~~ 发电了
-8. 开发过程中，每一定数量，记得提交一个 commit, 别忘了写上 message
-9. 完成开发后，推送本地分支到远程（自己）
+8. 开发过程中，每一定数量，记得提交一个 commit, 别忘了写上 message  
+    假如你不熟悉 git 的使用，你可能想要新建一个分支进行更改，而不是直接提交在 `dev` 上
+
+    ```bash
+    git branch your_own_branch
+    git checkout your_own_branch
+    ```
+
+    这样你的提交就能在新的分支上生长，不会受到 `dev` 更新的打扰
+
+9. 完成开发后，推送你修改过的本地分支（以 `dev` 为例）到远程（fork 的仓库）

    ```bash
    git push origin dev
    ```

 10. 打开 [MAA 主仓库](https://github.com/MaaAssistantArknights/MaaAssistantArknights)。提交一个 pull request，等待管理员通过。别忘了你是在 dev 分支上修改，别提交到 master 分支去了
-11. 当 MAA 原仓库出现更改（别人做的），你需要把这些更改同步到你 fork 的仓库
+11. 当 MAA 原仓库出现更改（别人做的），你可能需要把这些更改同步到你的分支
    1. 关联 MAA 原仓库

        ```bash
@@ -38,10 +47,16 @@
        git fetch upstream
        ```

-    3. 合并修改
+    3. 变基（推荐）或者合并修改

        ```bash
-        git merge
+        git rebase upstream/dev # 变基
+        ```
+
+        或者
+
+        ```bash
+        git merge # 合并
        ```

    4. 重复上述 7, 8, 9, 10 中的操作
--- a/docs/en-us/2.2-DEVELOPMENT.md
+++ b/docs/en-us/2.2-DEVELOPMENT.md
@@ -2,12 +2,12 @@

 ## Introduction to GitHub pull request flow

-1. If you have forked this repository before, please go to `Settings`, scroll down to the bottom, and click `Delete Repository`.
+1. If you have forked this repository long time ago, please go to `Settings`, scroll down to the bottom, and click `Delete Repository`.
 2. Go to [MAA main repository](https://github.com/MaaAssistantArknights/MaaAssistantArknights) and click `Fork`, then `Create fork`.
-3. Clone the `dev` branch of the repository (of your account) to local:
+3. Clone the `dev` branch of the (forked) repository to local:

    ```bash
-    git clone "your git repo link" -b dev
+    git clone <link to your forked repo> -b dev
    ```

 4. Configure development environment
@@ -17,15 +17,24 @@
 5. Double-click to open the file `MeoAssistantArknights.sln`. Visual Studio will load the project automatically.
 6. Run a build to test whether the development environment has been configured correctly. Chosse `Release` & `x64`, right-click `MeoAsstGui` to set it as the startup project, and run it. If the build is successful, the `MeoAsstGui` window will appear. You can connect to the emulator in order to confirm again that the development environment has been configured correctly.
 7. Now you are free to contribute to MAA.
-8. Remember to commit once you have proper number of changes. Don't forget to write a commit message.
-9. After development, push your local changes to the remote (of your repository).
+8. Remember to commit once you have proper number of changes. Don't forget to write a commit message.  
+    If you are a beginner of git, you might want to make changes on a newly created branch instead of commiting to `dev` directly
+
+    ```bash
+    git branch your_own_branch
+    git checkout your_own_branch
+    ```
+
+    so that your new commits would grow on the new branch, without being interrupted by updates of `dev`
+
+9. After development, push your local changes to the remote (your own repository).

    ```bash
    git push origin dev
    ```

 10. Go to [MAA repository](https://github.com/MaaAssistantArknights/MaaAssistantArknights) and submit a Pull Request. Wait until the administrator approves it. Please note that the changes should be based on `dev` instead of `master` branch, and should be merged to `dev` branch as well.
-11. When there are changes from other contributors on original MAA repository, it is necessary for you to merge them to your forked repository.
+11. When there are changes from other contributors on upstreaming MAA repository, it might be necessary for you to add them to your own branch.
    1. Add MAA upstream repository.

        ```bash
@@ -38,7 +47,13 @@
        git fetch upstream
        ```

-    3. Merge changes.
+    3. rebase (recommended) or merge changes.
+
+        ```bash
+        git rebase upstream/dev
+        ```
+
+        or

        ```bash
        git merge
--- a/docs/zh-tw/2.2-開發相關.md
+++ b/docs/zh-tw/2.2-開發相關.md
@@ -17,7 +17,16 @@
 5. 雙擊打開 `MeoAssistantArknights.sln` 檔案。 Visual Studio 會自動加載整個項目。
 6. 測試一下是否成功搭建編程環境，選擇參數 `Release`, `x64`, 右鍵 `MeoAsstGui` 設為啟動項目；點擊啟動，選擇繼續調試。如果成功打開了 GUI，就說明成功搭建了環境。如果求穩，可以繼續連接模擬器跑一下 MAA
 7. 到這裡，你就可以愉快地 ~~瞎 ㄐㄅ 改~~ 發電了
-8. 開發過程中，每一定數量，記得提交一個 commit, 別忘了寫上 message
+8. 開發過程中，每一定數量，記得提交一個 commit, 別忘了寫上 message  
+    假如你不熟悉 git 的使用，你可能想要新增一个分支，而不是直接提交在 `dev` 上
+
+    ```bash
+    git branch your_own_branch
+    git checkout your_own_branch
+    ```
+
+    這樣你的提交就能在新的分支上生長，不會被 `dev` 更新打擾
+
 9. 完成開發後，推送本地分支到遠端（自己）

    ```bash
@@ -25,7 +34,7 @@
    ```

 10. 打開 [MAA 主儲存庫](https://github.com/MaaAssistantArknights/MaaAssistantArknights)。提交一個 pull request，等待管理員通過。別忘了你是在 dev 分支上修改，別提交到 master 分支去了
-11. 當 MAA 原儲存庫出現更改（別人做的），你需要把這些更改同步到你 fork 的儲存庫
+11. 當 MAA 原儲存庫出現更改（別人做的），你需要把這些更改同步到你的分支
    1. 關聯 MAA 原儲存庫

        ```bash
@@ -38,10 +47,16 @@
        git fetch upstream
        ```

-    3. 合併修改
+    3. 變基（推薦）合併修改
+
+        ```
+        git rebase upstream/dev # 變基
+        ```
+
+        或

        ```bash
-        git merge
+        git merge # 合并
        ```

    4. 重複上述 7, 8, 9, 10 中的操作
@@ -60,4 +75,4 @@

 你也可以使用 `tools\ClangFormatter\clang-formatter.py` 來直接執行你的 clang-format 來進行格式化，只需要在項目根目錄下執行：

- `python tools\ClangFormatter\clang-formatter.py --clang-format=PATH\TO\YOUR\clang-format.exe --input=src\MeoAssistant`
+- `python tools\ClangFormatter\clang-formatter.py --clang-format=PATH\TO\YOUR\clang-format.exe --input=src\MeoAssistant`