參與貢獻

在正確的地方做一個小變更，再以 pull request 送出。

開始之前

• 先開一個 issue，或在現有的 issue 下留言。說明你想改什麼、為什麼。
• 等回覆之後再動手，免得做出不會被合併的東西。
• 先完成 設定開發環境，這樣你才能建置並執行 HolyArrs。

問題請到 Discord。想法請到 r/HolyArrs。Issues 只用來回報 bug 和放路線圖。

送出你的第一個 pull request

1. 找出你的變更屬於哪個模組。模組 裡的名稱和資料夾名稱一致，所以 Discord 通知不對，就是改 alerts。

2. 在 app/backend/internal/<module>/ 和 app/frontend/src/lib/<module>/ 裡做變更。一次只做一個修正或一個功能。

3. 先建置 Web App，再建置程式，然後在瀏覽器裡試試看。見 設定開發環境。

4. 執行 測試 裡的檢查。

   你應該不會看到任何失敗。

5. 如果你改了某個頁面，就執行它的端對端 project，例如 npm --prefix app/frontend run e2e -- --project=movies。

6. 開啟 pull request。連結到 issue，說明改了什麼、怎麼測試的，並為這個變更新增或更新測試。

7. 第一次送 pull request 時，bot 會請你簽署貢獻者授權協議。回覆它要求的那一句話就好。

注意

你保有自己作品的著作權。這份協議讓 HolyArrs 可以同時以 AGPL-3.0 和商業授權提供。合併進來的內容也會繼續以 AGPL-3.0 提供。全文在 .github/CLA.md。

選項

變更要去哪裡

變更	前往
新的路由	模組
新的模組	模組。請先開一個 issue
暫緩的功能	設定開發環境
發布新版	發布新版。僅限維護者

好的 pull request 長什麼樣

• 註解要說明程式碼為什麼這樣做。註解裡不要放路線圖編號、日期、人名或破折號。
• 除非 issue 本身就是在談用字，否則不要動 App 的用字。
• 已發布的 API 路徑、欄位名稱、設定鍵、資料表名稱和工作名稱都維持原樣。只新增，不重新命名。

如果沒有成功

症狀。 結構檢查失敗。 原因。 訊息會指出檔案和被違反的規則。 解決方式。 移動程式碼，或由較高的模組把單純的資料傳進來。見 模組。

症狀。 Web App 看起來是舊的。 原因。 程式提供的是它內嵌的那一版建置。 解決方式。 先重新建置 Web App，再建置程式。

症狀。 端對端測試無法啟動。 原因。 沒有安裝測試用的瀏覽器。 解決方式。 執行 npx --prefix app/frontend playwright install chromium。

給進階使用者

pull request 必須遵守的規則

• 模組只透過另一個模組的 service（Go）或 index.ts（Web）和它溝通。絕不透過它的 store 或檔案。
• SQL 只放在模組的 store*.go 檔案裡，而且只操作該模組自己的資料表。
• 只有在 2 個以上模組使用時，Web 元件才放進 lib/ui。
• 不要有 util、common、shared 或 helpers package。
• 所有對外的呼叫都經過 core/outbound。

測試會檢查這些規則，所以錯誤的匯入會讓建置失敗。完整清單和檢查名稱在 模組。

CI 會跑什麼

工作	執行內容
Web	check、lint、test、build，以及端對端測試套件
Go	在 amd64 和 arm64 上，以原生和模擬方式執行 go build、go vet 和 go test -timeout 60m ./...
Race	go test -race ./...
Contract	openapi.json 比對、每個路由的 scope 檢查、下載器測試套件
Fault and scale	當機、寫入緩慢、外部服務異常和記憶體的執行
Image	開發用 image 會建置、啟動並回報它的版本

長時間執行的細節在 測試。

相關頁面

• 設定開發環境
• 測試
• 架構