Lophine/docs/CONTRIBUTING_ZH_TW.md

為 Lophine 貢獻程式碼

English | 中文（簡體） | 中文（繁體） | 日本語

很高興你願意為這個專案貢獻！一般來說，我們對 PR 的審核標準相當寬鬆； 如果你可以照著下面的規則來，我們就能更快完成審核。

請使用個人帳號進行 Fork

我們會定期嘗試合併現有的 PR，如果內容有一些小問題，我們會直接幫你修改後合併。

但如果你的 PR 是用組織（organization）帳號 fork 出來的，我們就沒辦法直接修改你的 PR，只能先關閉、再手動合併一次。

所以，請不要用組織帳號來 fork 這個專案！

你可以參考這個 Issue，了解為什麼我們沒辦法直接修改組織帳號的 PR。

開發環境

在開始寫程式之前，你需要先準備好以下開發工具與環境：

• git
• JDK 25 或更新版本

特別提醒：動手之前，請先在你的作業系統與 Git 裡啟用長路徑（long path）支援，以下是部分平台的設定說明。

Windows Git for Windows

認識 Patch（補丁）系統

Lophine 沿用了和 Folia 相同的 patch 系統，並依照修改的部分分成了兩個目錄：

• lophine-api - 基於 Folia-API / Paper-API / Spigot-API / Bukkit-API 所做出的修改。
• lophine-server - 針對 Minecraft 原版伺服器既有邏輯所做的修改。

這套 patch 系統是以 git 為基礎運作的，你可以在這裡了解 git 的基本操作：https://git-scm.com/docs/gittutorial

如果你已經 fork 了主要的 repository，接下來請照以下步驟操作：

1. 把你 fork 出來的 repository clone 到本機；
2. 在你的 IDE 或終端機（terminal）裡執行 Gradle 的 applyAllPatches 任務；如果是在終端機裡，可以直接執行 ./gradlew applyAllPatches；
3. 執行完成後，repository 的根目錄下應該會出現以下幾組目錄： lophine-api 與 lophine-server、folia-api 與 folia-server 以及 paper-api 與 paper-server（以下統稱為 *-api 與 *-server）；
4. 進入 repository 根目錄下對應的 *-api 與 *-server 資料夾，在裡面進行修改。

以下是對上述各個資料夾的簡單說明，更詳細的說明可以參考這裡：

1. API 部分

• lophine-api：新增 API 的修改請放在這裡
• folia-api：針對 Folia API 的修改請放在這個資料夾
• paper-api：對於 Paper API / Spigot API / Bukkit API 的修改請放在這個資料夾

2. Server 部分

• lophine-server：針對 Minecraft 原版伺服器的修改、以及新增的檔案，都請放在這個資料夾
• folia-server：針對 folia-server 的修改請放在這個資料夾
• paper-server：根據 Paper 伺服器邏輯的修改請放在這個資料夾

順帶一提，repository 根目錄下的 *-api 與 *-server 並不是一般的 git repository：

• 在套用 patch 之前，base（基準點）指向的是未經修改的原始程式碼；
• base 之後的每一個 commit，都會被視為一個 patch；
• 只有在 Folia 最後一個 commit 之後的 commit，才會被視為是 Lophine 的 patch。

新增 Patch

依照以下步驟新增一個 patch 非常簡單：

1. 在 *-api 與 *-server 裡進行修改；
2. 用 git 把你的修改加入暫存區，例如執行 git add .（請不要把新建立的檔案一併加入）；
3. 執行 git commit -m <提交訊息> 進行 commit；
4. 執行 Gradle 任務 fixupPaperApiFilePatches，用於新建立的檔案產生對應的 patch 檔（注意：執行完之前先不要 commit）；
5. 執行 Gradle 任務 rebuildAllServerPatches，用於把你的 commit 轉換成一個 patch；
6. 把產生出來的 patch 檔 push 上去。

完成以上步驟後，你就可以拿這些 patch 檔開 PR 提交了。

修改 Patch

你可以用以下方法來修改一個既有 patch 的內容：

1. 直接在 HEAD 上進行修改；
2. 執行 git commit -a --fixup <hash> ，做一個 fixup commit（請不要把 Lophine 新建立的檔案的修改一併 commit 進去）；
   • 如果你想順便修改 commit 訊息，可以用 --squash 取代 --fixup。
3. 執行 git rebase -i --autosquash base ，進行自動 rebase，接著只要輸入 :q 關掉確認頁面即可；
4. 執行 Gradle 任務 fixupPaperApiFilePatches，用於重新產生 Lophine 新建立檔案的 patch（注意：執行完之前先不要 commit）；
5. 執行 Gradle 任務 rebuildAllServerPatches，把修改套用到既有的 patch 上；
6. 把修改後的 patch 重新 push 回去，再開一次 PR。

為設定項目提供本地化的注解支援

1. 在 lophine-server/src/main/resources/assets/lophine/lang 目錄下新增或修改對應語言的檔案，加入本地化的注解；
   • 檔名請依照 https://minecraft.wiki/w/Language 頁面上列出的語言代碼來命名，例如 en_us、zh_cn、zh_hk、zh_tw，檔案格式為 json；
2. 執行 Gradle 任務 sortLangKeys，把你修改的語言檔內容重新排序；
3. 執行 git commit -m <提交訊息> 進行 commit；
4. 把你修改的檔案 push 上去。

完成以上步驟後，你就可以拿修改後的內容開 PR 提交了。