為 Remix 做出貢獻

我們的目標是讓 Remix 的開發穩定、可靠且開放。沒有我們優秀的使用者社群，我們無法做到這一點！

本文將使您熟悉我們的開發流程以及如何設定您的環境。

為確保您的工作有最大的機會被接受，請在貢獻任何內容之前閱讀本文！

貢獻者授權協議

所有發送 Pull Request 的貢獻者都需要簽署貢獻者授權協議 (CLA)，該協議明確將貢獻的所有權分配給我們。

當您開始一個 pull request 時，remix-cla-bot 會提示您查看 CLA 並透過將您的姓名新增至 contributors.yml 來簽署它。

閱讀 CLA

角色

本文將貢獻者分為以下角色

• 管理員：具有管理權限的 GitHub 組織團隊，他們設定和管理路線圖。
• 協作者：具有寫入權限的 GitHub 組織團隊。他們管理 issues、PRs、討論等。
• 貢獻者：您！

開發流程

功能開發

如果您有新功能的想法，請不要發送 Pull Request，而是遵循此流程

1. 貢獻者將提案新增至 GitHub Discussions。
2. Remix 管理員團隊在路線圖規劃會議中接受提案。
   • 當管理員從提案中建立 Issue 並將 issue 新增至 路線圖 時，提案即被接受。
3. 管理員將 Owner（負責人） 指派給 issue。
   • 負責人負責交付該功能，包括所有 API、行為和實作的決策。
   • 負責人與其他貢獻者一起組織較大 issue 的工作。
   • 負責人可能是來自 Remix 團隊內部或外部的貢獻者。
4. 負責人從提案中建立 RFC，然後可以開始開發。
5. 強烈鼓勵配對，尤其是在開始時。

錯誤修復 Pull Request

如果您認為您發現了一個錯誤，我們很樂意收到修復它的 PR！請遵循以下準則

1. 貢獻者在 Pull Request 中新增一個失敗的測試以及修復程式碼。
   • 理想情況下，第一個 commit 是一個失敗的測試，然後是修復程式碼的變更。
   • 這並非嚴格強制執行，但非常感謝！
2. 管理員將在路線圖規劃中審查未解決的錯誤修復 PR。
   • 簡單的錯誤修復將立即合併。
   • 其他錯誤修復將新增至路線圖並指派一位負責人來審查工作並使其完成。

沒有測試案例的錯誤修復 PR 可能會立即關閉（有些事情很難測試，我們會在此處酌情處理）

錯誤回報問題

如果您認為您發現了一個錯誤，但沒有時間發送 PR，請遵循以下指南

1. 在 Stackblitz、Replit、CodeSandbox 等地方建立一個最小化的問題重現範例，以便我們可以瀏覽並觀察錯誤

   • https://remix.new 讓這件事變得非常容易

2. 如果這不可行（與某些主機設定等有關），請建立一個 GitHub 儲存庫，我們可以在 README 中使用明確的指示來執行它以觀察錯誤。

3. 開啟一個 issue 並連結到重現範例。

沒有重現範例的錯誤回報將會立即關閉，並要求提供重現範例。

路線圖規劃會議

您隨時可以在我們的直播規劃會議中查看 Remix 的開發進度

• Remix 管理團隊將每週開會，向社群報告進度，並將提案和已驗證的錯誤添加到路線圖中。
  • 將提案添加到路線圖需要 Remix 管理團隊之間的一致同意。
  • 提案不會被「拒絕」，只會被「接受」到路線圖上。
  • 貢獻者可以繼續對提案進行投票和評論，如果它獲得新的活動，它們將在未來審查時浮出水面。
  • Remix 管理團隊可能會因任何原因鎖定提案。
• 會議將在 Remix YouTube 頻道上直播。
  • 在會議進行時，歡迎所有人加入 Discord 的 #roadmap-livestream-chat 頻道。
  • 邀請 Remix 協作者參加。

Issue 追蹤

如果路線圖上的 Issue 預計很大（涉及多個任務、作者、PR 等），管理團隊將建立一個臨時專案看板。

• 原始 issue 將保留在路線圖專案上，以查看整體進度。
• 子任務將在臨時專案上進行追蹤。
• 當工作完成時，臨時專案將被歸檔。
• 負責人負責將 issue 填入子專案，並將工作劃分為可發佈的區塊。
• 鼓勵使用建置/功能旗標，而不是長時間運行的分支。

RFC

• 所有計畫中的 Issue 都必須在 Issue 從已計劃移動到進行中之前，在官方 RFCs 討論類別中發布 RFC。
• 某些提案可能已經是一個足夠的 RFC，可以簡單地移動到官方 RFCs 討論類別。
• 一旦發布 RFC，就可以開始開發，但預期負責人會考慮社群的回饋，以便在需要時改變方向。

對負責人的支援

• 負責人將被添加到 Discord 的 #collaborators 私人頻道中，以獲得架構和實作方面的幫助。此頻道是私人的，以盡量減少干擾，以便管理員不會錯過訊息，並且負責人可以順利解決問題。負責人也可以在任何頻道或任何地方討論這些問題！
• 管理員將積極與負責人合作，以確保他們的 issue 和專案組織良好（正確的狀態、相關 issue 的連結等）、有文件記錄並持續推進。
• 如果進度停滯，issue 的負責人可能會被重新分配。

每週路線圖審查

每週一次，Remix 團隊和任何外部負責人都會被邀請審查路線圖

• 找出阻礙
• 在團隊和社群中尋找配對機會

協作者的角色

為了保持儲存庫的清潔和井然有序，協作者將採取以下行動

Issues 標籤

• 沒有重現範例的錯誤回報將會立即關閉，並要求提供重現範例。
• 應為提案的 Issue 將會被轉換為提案。
• 問題將會被轉換為問答討論。
• 具有有效重現範例的 Issue 將被標記為已驗證的錯誤，並由管理員在路線圖規劃會議中添加到路線圖中。

Pull Requests 標籤

• 未經過開發流程的功能將立即關閉，並要求開啟討論。
• 沒有測試案例的錯誤修復 PR 可能會立即關閉，並要求提供測試。（有些事情很難測試，協作者將在此處酌情處理。）

開發設定

在您可以為程式碼庫做出貢獻之前，您需要 fork 儲存庫。這會根據您所做的貢獻類型而略有不同

以下步驟將幫助您設定好為此儲存庫貢獻變更

1. Fork 儲存庫（點擊 此頁面右上角的 Fork 按鈕）。

2. 在本地複製您的 fork。

   # in a terminal, cd to parent directory where you want your clone to be, then
   git clone https://github.com/<your_github_username>/remix.git
   cd remix
   
   # if you are making *any* code changes, make sure to checkout the dev branch
   git checkout dev
   

3. 執行 pnpm 安裝依賴項。如果您使用 npm 安裝，將會產生不必要的 package-lock.json 檔案。

4. 執行 npx playwright install 安裝 Playwright 以便能夠正確執行測試，或者使用 Visual Studio Code 外掛程式。

5. 執行 pnpm test 以驗證您是否已為本機開發設定好所有內容。

分支

重要：在 GitHub 中建立 PR 時，請確保將基礎設定為正確的分支。

• dev 用於程式碼變更。
• main：用於文件和某些範本的變更。

您可以在撰寫 PR 時，使用「比較變更」標題下方的下拉式選單，在 GitHub 中設定基礎。

測試

我們在這個專案中使用 jest 和 playwright 的組合進行測試。我們在 integration 資料夾中有一套整合測試，並且套件都有自己的 jest 設定，然後在專案根目錄中的主要 jest 設定中引用這些設定。

整合測試和主要測試可以使用 npm-run-all 並行執行，以使測試盡可能快速且有效率地執行。要獨立執行這兩組測試，您需要執行個別的腳本

• pnpm test:primary
• pnpm test:integration

我們也支援用於專案、檔案和測試篩選的監看外掛程式。若要篩選，您可以使用 --testNamePattern、--testPathPattern 和 --selectProjects 的組合。例如

pnpm test:primary --selectProjects react --testPathPattern transition --testNamePattern "initial values"

我們也有這些的監看模式外掛程式。因此，您可以執行 pnpm test:primary --watch 並點擊 w 以查看可用的監看命令。

或者，您可以完全獨立地執行一個專案，方法是 cd 到該專案中並執行 pnpm jest，這將會擷取該專案的 jest 設定。

開發工作流程

套件

Remix 使用單一儲存庫來託管多個套件的程式碼。這些套件位於 packages 目錄中。

我們使用 pnpm workspaces 來管理依賴項的安裝和執行各種腳本。要安裝所有內容，請從儲存庫根目錄執行 pnpm install。

建置

從根目錄執行 pnpm build 將會執行建置。您可以使用 pnpm watch 在監看模式下執行建置。

遊樂場

在為應用程式開發功能時，能夠與真實應用程式互動通常非常有用。因此，您可以將應用程式放置在 playground 目錄中，建置過程會自動將所有輸出複製到 playground 目錄中所有應用程式的 node_modules 中。它甚至會為您觸發即時重新載入事件！

若要產生新的遊樂場，只需執行

pnpm playground:new <?name>

其中遊樂場的名稱是可選的，預設為 playground-${Date.now()}。然後您可以 cd 到為您產生的目錄中並執行 npm run dev。在另一個終端機視窗中，讓 pnpm watch 正在執行，您就可以使用即時重新載入魔法🧙‍♂️來處理任何您喜歡的 Remix 功能。

從 pnpm playground:new 產生的遊樂場是基於 scripts/playground/template 中的範本。如果您想變更範本的任何內容，您可以在 scripts/playground/template.local 中建立自訂範本，該範本是 .gitignored 的，因此您可以根據自己的喜好進行自訂。

測試

在執行測試之前，您需要執行建置。建置完成後，從根目錄執行 pnpm test 將會執行每個套件的測試。如果您想執行特定套件的測試，請使用 pnpm test:primary --selectProjects <display-name>

# Test all packages
pnpm test

# Test only @remix-run/express
pnpm test:primary --selectProjects express

儲存庫分支

此儲存庫維護用於不同目的的獨立分支。它們看起來會像這樣

- main   > the most recent release and current docs
- dev    > code under active development between stable releases

可能還有其他分支用於各種功能和實驗，但所有的魔法都來自這些分支。

夜間發布如何運作？

夜間發布將從 main 分支執行 action 檔案，因為排程的工作流程將始終使用預設分支的最新 commit，由夜間 action 檔案上的此註解表示，但是它們在設定期間會檢查 dev 分支，因為那是我們希望夜間發布所依據的分支。從那裡，我們檢查 git SHA 是否相同，並且僅在發生變更時才會發布新的夜間版本。

端對端測試

對於 Remix 的每次發布（穩定版、實驗版、夜間版和預發布版），我們都會對來自 create-remix 的每個官方轉接器上的 Remix 應用程式進行完整的端對端測試，一直到將它們部署到生產環境。我們透過使用預設的範本和 Fly 和 Arc 的 CLI 來做到這一點。然後，我們將執行一些簡單的 Cypress 斷言，以確保開發和部署的應用程式都能正常執行。