> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/zh-tw/contributing/how-to-contribute.md).

# 如何貢獻

分支規範、拉取請求指南，以及 commit 訊息風格。

MyIP 是開放原始碼，歡迎外部貢獻。本頁說明此專案實際採用的流程，從第一個 issue 到合併完成的 pull request。

這裡的一切都對應著 [`CONTRIBUTING.md`](https://github.com/jason5ng32/MyIP/blob/main/CONTRIBUTING.md) 與 `AGENTS.md` 在儲存庫中。此專案還有一份 [行為準則](https://github.com/jason5ng32/MyIP/blob/main/CODE_OF_CONDUCT.md) （Contributor Covenant）。參與即表示你同意遵守它。

## 在你寫程式碼之前

任何非瑣碎的事項，先開一個 issue。事前簡短討論比一個被退回的 pull request 便宜得多。新增功能、行為變更、新依賴，以及重構都算。

小而明顯的修正——錯字、失效連結、單行 bug——可以直接提交 pull request。

如果你是這個專案的新手，請尋找標示為 `good first issue`.

## 流程

{% stepper %}
{% step %}

### 開立 issue

描述變更內容以及為何需要它。先等待維護者確認方向，再投入時間。請參見 [回報問題](/developer/zh-tw/contributing/reporting-issues.md).
{% endstep %}

{% step %}

### Fork 並從以下分支建立分支： `dev`

Fork 該儲存庫，然後從以下分支建立你的分支： **`dev`** ——不是 `main`.

```bash
git clone https://github.com/<you>/MyIP.git
cd MyIP
git checkout dev
git checkout -b fix/mac-input-validation
```

{% endstep %}

{% step %}

### 設定並建置

使用 pnpm 安裝並讓應用程式跑起來。請參見 [開發環境](/developer/zh-tw/development/dev-environment.md).

```bash
pnpm install
pnpm dev
```

{% endstep %}

{% step %}

### 進行變更

每個分支只處理一個議題。遵循 [編碼慣例](/developer/zh-tw/development/coding-conventions.md)，並在以下位置新增或更新測試： `tests/` 針對你動到的任何非視覺邏輯。
{% endstep %}

{% step %}

### 執行 `pnpm check`

`pnpm check` 會執行測試套件和正式版建置。推送前必須全部通過。

```bash
pnpm check
```

{% endstep %}

{% step %}

### 重新 rebase 到最新的 `dev`

Rebase——不要 merge `dev` 到你的分支上。這樣可讓歷史紀錄更易讀。

```bash
git fetch upstream
git rebase upstream/dev
```

{% endstep %}

{% step %}

### 對以下分支開啟 pull request： `dev`

請填寫 pull request 範本：摘要、變更類型，以及檢查清單。附上它所修正的 issue 連結。
{% endstep %}
{% endstepper %}

## 為什麼 pull request 目標是 `dev`

{% hint style="warning" %}
**絕不要對以下分支開啟 pull request： `main`.** `main` 只會接收來自以下分支的發佈合併： `dev` 分支。以 `main` 為目標的 pull request 會被要求改投向其他分支。
{% endhint %}

儲存庫是 `dev` 進入， `dev` 離開。所有工作都先落在 `dev` 首先； `main` 只會透過一個 `dev` → `main` 發佈合併進行。這能讓 `main` 與已發佈內容保持一致，也代表每個變更都會先在 `dev` 首先。

## pull request 規則

* **目標 `dev`.** 請見上文。
* **每個 pull request 只處理一個議題。** 不要把功能和無關的開發環境調整綁在一起。請拆開。
* **提交前先 rebase**，讓你的分支建立在目前的 `dev`.
* **說明改了什麼，以及為什麼要改。** 審查者不應該從 diff 反向推測你的意圖。
* **`pnpm check` 綠燈。** CI 會執行 `pnpm test` 與 `pnpm run build` 針對每個 pull request 在 Node 24 上 `dev` 或 `main`；若執行結果為紅燈，會阻擋合併。

## Commit 訊息格式

commit 採用 `Type(scope):` 前綴，沿用專案自身的歷史慣例。scope 是可選的，用來命名受影響的區域（`ui`, `api`，例如功能名稱、模組名稱）。

| 前綴              | 用於         | 來自儲存庫的實際範例                                             |
| --------------- | ---------- | ------------------------------------------------------ |
| `Feat(...)`     | 新功能        | `Feat(ui)：為 MTR / 延遲 / 封鎖檢測共用 Globalping 國家選擇器`        |
| `Fix(...)`      | 錯誤修正       | `Fix(ui)：讓 MAC 輸入驗證與後端一致（恰好 12 個十六進位數字）`               |
| `Refactor(...)` | 重構，無行為變更   | `Refactor(country-name)：以 Intl.DisplayNames 取代手動維護的表格` |
| `Perf(...)`     | 效能優化       | `Perf(frontend)：僅延遲載入目前使用中的 UI 語言環境`                   |
| `Style(...)`    | 視覺或文案潤飾    | `Style(toggle)：為切換元件提供高對比的按下狀態`                        |
| `Chore(...)`    | 工具、依賴、日常整理 | `Chore：簡化 jsconfig 路徑對應`                               |

訊息請用英文、祈使語氣，且每個 commit 只處理一個議題。

## i18n 規則

UI 提供的語言皆來自同一個中央登錄表， `common/locale-registry.js`。每個都帶有一個 `狀態`：一個 **`完整的`** locale 是每次文案變更都必須落地的狀態，一個 **`beta`** 可以只發佈部分語言包，並回退為英文。登錄表本身就是目前哪個 locale 擁有何種狀態的清單。

{% hint style="danger" %}
任何會影響使用者可見文案的變更都必須更新 **每一個 `完整的` 同一個 commit 中的 locale 檔案** ——包括 `frontend/data/changelog.json` 項目。 `tests/locale-packs.test.js` 與 `tests/changelog.test.js` 會強制執行這項規則，因此 `pnpm check`.
{% endhint %}

如果你無法有把握地撰寫某個 locale，仍然請先把該 key 以你最好的嘗試加入每個檔案，並在 pull request 中說明。詳情： [i18n](/developer/zh-tw/development/i18n.md).

**新增一種語言是另一項不同且小得多的工作** ——只限前端，並由 `pnpm i18n-new <code>`，而部分翻譯是很受歡迎的第一個 PR。請參見 [翻譯 MyIP](/developer/zh-tw/contributing/translating.md).

## 測試

不需網路呼叫即可執行的非視覺邏輯——純函式、驗證器、轉換器、可用 mock 輸入的 composables——會在 `tests/` 的同一個變更中附上規格。UI 渲染、真實網路行為，以及瀏覽器 API 不在範圍內。請參見 [測試](/developer/zh-tw/development/testing.md).

## 程式碼審查

每個 pull request 都會由維護者審查。請預期會有提問、要求修改，或在合併前針對做法進行討論。這很正常，不代表被拒絕。

將後續 commit 推送到同一個分支——pull request 會自動更新。如果你的變更是視覺性的，且無法在無頭模式下驗證，請明說，並附上截圖或短錄影。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ipcheck.ing/developer/zh-tw/contributing/how-to-contribute.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.