參與貢獻 Docusaurus

Docusaurus 是我們希望讓開源文件編寫更輕鬆的方式。目前我們有 多個使用此工具的開源專案，而且還有更多專案正在規劃之中。如果您有興趣參與貢獻 Docusaurus，希望這份文件能讓參與貢獻的流程更加清楚。

開放原始碼指南 網站會彙整資源，提供給想學習如何執行並貢獻開源專案的個人、社群和公司。對於貢獻者和初次接觸開源的人來說，以下指南特別實用

• 如何參與開源專案
• 打造熱情的社群

行為規範

Facebook 已採行我們預期專案參與者應遵守的行為規範。請閱讀 全文，這樣您就能了解哪些行為可以被容忍，哪些行為不得被容忍。

參與活動

有很多方式可以協助 Docusaurus，其中很多都與編寫程式碼無關。以下是開始的一些構想

• 開始使用 Docusaurus。瀏覽入門指南。一切都按照預期運作嗎？如果不是，我們隨時在尋找進步空間。請透過開啟問題讓我們知道。
• 瀏覽開放問題。提供解決方案、要求澄清或建議標籤。協助分類問題。
• 如果您發現您願意解決的問題，請開啟拉取請求。標示為初次問題 的問題是開始著手的好地方。
• 閱讀Docusaurus 文件。如果您發現任何內容令人困惑或可以改進，您可以在大部分文件的底部按一下「編輯此頁面」，這會將您帶往 GitHub 介面，可以提出變更並提出建議。
• 查看社群中其他人請求的功能，如果您看到您想著手處理的事項，可以考慮開啟拉取請求。

我們非常歡迎貢獻。如果您認為需要協助規劃您的貢獻，請在 Twitter 上透過@docusaurus 呼叫我們，讓我們知道您需要一些協助。

加入我們的 Discord 頻道

我們在Discord 上有#contributors 頻道，討論有關 Docusaurus 開發的所有事情。您也可以在#help-and-questions 頻道中協助其他使用者，提供很大的協助。

分類問題和拉取請求

在不編寫任何程式碼的情況下，幫助解決問題和拉取請求是您對專案做出貢獻的其中一個好方法。

• 如果您認為問題沒有提供解決所需的所有詳細資料，請要求提供更多資訊。
• 建議可用於分類問題的標籤。
• 標記已過時或應該關閉的問題。
• 要求測試計畫和檢閱程式碼。

我們的開發程序

Docusaurus 使用 GitHub 作為其權威來源。核心團隊將直接在上面作業。所有變更從一開始就公開。

所有プルリクエスト都會由持續整合系統 GitHub actions 檢查。有單元測試、端對端測試、效能測試、風格測試等等更多。

分支組織

Docusaurus 有主要分支 main 和使用具有部署預覽的功能分支，以透過 プルリクエスト提交交付新功能。

問題

當 開啟新問題 時，請務必填寫問題範本。此步驟非常重要！未完成可能會導致您的問題無法在合理的時間內獲得解決。如果發生這種情況，請不要因此生氣，在收集範本所需的所有資訊後，隨時都可以開啟新的問題。

請勿對 GitHub 問題追蹤功能使用疑問。如果您對 Docusaurus 的使用有任何疑問，請使用我們的任何 支援管道，我們將盡力回答您的問題。

錯誤

我們對公開錯誤使用 GitHub 問題 。如果您要回報問題，請四處看看是否有人已經開啟相關問題。如果您確定這是一個全新的未回報錯誤，則可以提交一個 錯誤回報。

• 一個問題，一個錯誤：請每個問題回報一個錯誤。
• 提供重複步驟：列出重複問題所需的所有步驟。閱讀您的錯誤回報的人員應該能夠遵循這些步驟以最少的步驟重複您的問題。

如果您只修正一個錯誤，則可以直接提交 プルリクエスト，但我們仍建議您提交問題，詳細說明您正在修正什麼。如果我們不接受該特定修正，但想要追蹤問題，這將會有幫助。

安全性錯誤

Facebook 有 賞金計畫 以安全揭露安全性錯誤。有鑒於此，請勿提交公開問題；請遵循該頁面上列出的流程。

功能要求

如果您想要求新增功能或加強功能，但尚未考慮開啟拉取請求，您可以使用功能範本以詳盡的 RFC格式提交議題。或者，您可以使用Canny 公告欄提出較為隨意的功能請求，並在提出 RFC 之前獲得足夠的關注度。

建議

如果您打算對現有實現進行任何非瑣碎的變更，我們建議您使用建議範本提交議題。這讓我們能夠在您投入大量心力之前就達成共識。這類型的議題應該很少見。

認領議題

我們有一份適合初學者的議題清單，可協助您了解 Docusaurus 程式碼庫並熟悉我們的貢獻流程。這是入門的好地方。

除了適合初學者的議題之外，下列標籤也很值得關注

• 需要協助：如果您在某個領域有專業知識，處理這些議題可以讓您的專業技能發光發熱。
• 狀態：接受 PR：社群貢獻者可以放心認領任何這些議題。

如果您想要處理這些議題中的任何一個，請留言表示「我想處理這個議題」，我們將把議題指派給您，並將議題狀態更新為「已認領」。您預計在之後的七天內送出拉取請求，這樣如果無法處理，我們可以將議題委派給其他人。

或者，在開啟議題時，您也可以勾選「自助服務」核取方塊，表示您想自己處理這個議題，這也會讓我們視該議題為「已認領」。

開發

線上一次按鍵完成協助設定

您可以使用 Gitpod（一個免費的線上 類似 VS Code 的 IDE）來協助貢獻。只要按一下，即可啟動工作空間（適用於 Docusaurus 2），並自動

• 複製 docusaurus 儲存庫。
• 安裝依賴項。
• 執行 yarn start

這樣就可以直接開始貢獻。

同時也可以嘗試使用新的 github.dev 功能。瀏覽任何檔案的同時，將網域名稱從 github.com 變更為 github.dev，這樣就會將瀏覽器轉換為線上編輯器。您可以開始編輯並馬上發送提交要求。

安裝

1. 請務必已安裝 Yarn。
2. 複製存放庫後，請在存放庫根目錄執行 yarn install。這會安裝所有依賴項，以及建置所有本機套件。
3. 若要啟動開發伺服器，請執行 yarn workspace website start。

程式碼規範

• 最重要：四周看看。符合在專案其他部分使用的樣式。其中包括格式、命名檔案、命名程式碼中的項目、命名文件中的項目等。
• 「簡潔明瞭」
• 我們採用 Prettier（格式化程式）和 ESLint（句法檢查器）來找出大多數的文體問題。如果您在本機電腦工作，這些工具在每次 git commit 提交時就應該自動修正一些問題。
• 文件：不要在 80 個字元處折行 - 編輯文件時，設定編輯器為自動換行。

別太在意一般樣式—維護人員會在檢閱您的程式碼時協助您修正這些問題。

提交要求

因此，您已決定透過開啟提交要求，將程式碼貢獻回上游。您已投入大量時間，我們很感激。我們會盡力與您合作，並檢視提交要求。

在處理您的第一個提交要求？您可以觀看此免費影片系列，瞭解如何處理：

如何對 GitHub 上的開源專案做出貢獻

提交提交要求時，請務必執行下列事項

1. 提交要求務必簡短。簡短的提交要求（約 300 行差異）比較容易檢閱，且較有可能合併。請確定提交要求只做一件事，否則請將其拆分。
2. 使用描述性的標題。建議遵循此 提交訊息樣式。
3. 測試變更。在提交要求說明中說明您的 測試計畫。
4. CLA。如果您尚未簽署 CLA，請簽署。

所有提交要求都應對應開在 main 分支上。

我們有許多執行自動化測試的整合系統來防止發生錯誤。維護人員也會檢視您的程式碼，並修正對您而言顯而易見的問題。這些系統的職責是讓您盡可能減少對例行工作的擔憂，儘管完成檢查清單必定能節省大家的時間，但您的程式碼貢獻比遵循任何程式更重要。

語意化提交訊息

瞭解如何透過略為變更提交訊息樣式，讓您成為更優秀的程式設計師。

格式：<類型>(<範疇>): <主旨>

<範疇> 是選填。如果您的變更特定於一個或兩個套件，請考慮加入範疇。範疇應簡潔，但須可辨識，例如 content-docs、theme-classic、core

各式各樣的提交

• feat：新的 API 或行為針對最終使用者。
• fix：修正錯誤針對最終使用者。
• docs：變更我們的存放庫中的網站或其他標記文件。
• refactor：對生產程式碼的變更，不會造成行為上的差異，例如：分割檔案、重新命名內部變數、改善程式碼風格...
• test：新增遺失的測試、重構測試；沒有對生產程式碼進行變更。
• chore：升級相依性、釋出新版本...定期執行的維護工作。
• misc：所有其他未變更生產程式碼，但並非 test 或 chore 的內容，例如：更新 GitHub 動作工作流程。

但請別太過在意公關標題。您的公關會合併壓縮，而您對 main 分支提交的訊息將會取得公關的標題，因此分支內的提交不需要語意化命名。維護人員將會協助您建立正確的公關標題，而且我們也有公關標記系統，與提交訊息類型無關。您的程式碼比慣例更重要！

範例

feat(core): allow overriding of webpack config
^--^^----^  ^------------^
|   |       |
|   |       +-> Summary in present tense. Use lower case not title case!
|   |
|   +-> The package(s) that this change affected.
|
+-------> Type: see above for the list we use.

版本化文件

如果您只想進行文件變更，您只需認識版本化文件即可。

• website/docs - 此處檔案負責在 https://docusaurus.dev.org.tw/docs/next/installation 的「下一個」版本。
• website/versioned_docs/version-X.Y.Z - 這是 https://docusaurus.dev.org.tw/docs/X.Y.Z/installation 的 X.Y.Z 版本文件。

不要編輯 versioned_docs/ 或 versioned_sidebars/ 內自動產生的檔案，除非您確定有必要。例如，關於新功能的資訊不應記錄在版本化文件中。對舊版本所做的編輯，將不會傳播到更新版本的說明文件中。

測試計畫

良好的測試計畫包含您執行確切命令以及其產出的內容，如果拉取請求變更使用者介面，請提供螢幕擷取畫面或影片。如果您變更 API，請更新文件。

測試整合到我們的持續整合系統中，因此您不一定需要執行本機測試。不過，對於重大的程式碼變更，如果您可以在本機先做詳盡的測試以確保您的 PR 處於良好狀態，將會為您和維護人員節省時間。有許多類型的測試

• 編譯和類型檢查。我們在程式碼庫中使用 TypeScript，這可以確保您的程式碼一致，並及早偵測某些明顯的錯誤。
• 單元測試。我們使用 Jest 針對 API 端點的行為進行單元測試。您可以在根目錄執行 `yarn test` 以執行所有測試，或執行 `yarn test path/to/your/file.test.ts` 以執行特定測試。
• 內部體驗。我們的網站本身涵蓋所有潛在的設定案例，我們甚至有一個專用的 測試區域。請不要害怕在您的 PR 中更新我們網站的設定——這可以幫助維護人員預覽影響。我們可以在合併和部署到生產環境時決定是否保留網站變更。
• E2E 測試。您可以模擬散布和安裝帶有新變更的程式碼。如果您需要協助在本地端測試變更，您可以查看關於執行 本地端第三方測試 的文件。

授權

透過為 Docusaurus 做出貢獻，您同意您的貢獻將依據其 MIT 授權而授權。將此複製貼上到您新的檔案頂端

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

這也能使用 header/header ESLint 規則自動修正。

貢獻者授權合約 (CLA)

為了接受您的拉取請求，我們需要您提交 CLA。您只需要執行一次，因此如果您已經為另一個 Facebook 開源專案執行過，那就沒問題了。如果您是第一次提交拉取請求，Facebook GitHub Bot 將會回覆一個連結到 CLA 表單。您也可以 在此完成您的 CLA。

您簽署 CLA 後，CLA 機器人會自動更新 PR 狀態。不需要開啟新的 PR。

我們需要 CLA 才能合併您的プルリクエスト。 我們重視您的努力，並願意等您回來後解決評核 (如果您在發送プルリクエスト後無法回覆的話)，但若有已準備好合併但缺乏 CLA 且作者未回應的プルリクエスト，我們將會在開啟後兩週內關閉。如果您對 CLA 有任何進一步的問題，請持續與我們保持聯繫。

如果您無法使用而您的 PR 被關閉，只要準備好時都可以重新開啟！我們還是會很樂意審查您的 PR，協助您完成，並最終進行合併。

重大變更

當您新增重大的變更時，請在您的プル請求中遵循此範本

### New breaking change here

- **Who does this affect**:
- **How to migrate**:
- **Why make this breaking change**:
- **Severity (number of people affected x effort)**:

接下來會發生什麼事？

Docusaurus 核心團隊將會監視プル請求。請透過遵循上述準則來維持プル請求一致性的方式協助我們。