LLVM 開發者政策

簡介

本文档包含 LLVM 開發者政策，該政策定義了專案對開發者及其貢獻的政策。此政策的目的是消除可能因 LLVM 開發的分散性質而產生的溝通不良、返工和混亂。通過以清晰的條款說明政策，我們希望每位開發者都能預先知道在為 LLVM 做出貢獻時會發生什麼。此政策涵蓋所有 llvm.org 子專案，包括 Clang、LLDB、libc++ 等。

此政策還旨在達成以下目標

  1. 吸引使用者和開發者加入 LLVM 專案。

  2. 盡可能簡化和方便貢獻者的生活。

  3. 盡可能保持程式碼樹頂端的穩定性。

  4. 建立專案的 著作權、許可證和專利政策 意識，讓貢獻者了解專案的相關規範。

此政策的目標是 LLVM 的頻繁貢獻者。有興趣貢獻一次性補丁的人可以通過將其發送到 llvm-commits 郵件列表，並與另一位開發者合作完成整個流程，以非正式的方式進行。

開發者政策

本節包含與頻繁 LLVM 開發者相關的政策。我們始終歡迎來自不常貢獻 LLVM 的人員的 一次性補丁，但我們對頻繁貢獻者有更高的期望，以盡可能提高每個人的系統效率。為了讓 LLVM 維持高標準的品質，頻繁的 LLVM 貢獻者應符合以下要求。

保持資訊暢通

開發者應閱讀 LLVM Discourse 論壇，並訂閱感興趣的類別以接收通知，以保持資訊暢通。

關注其他人正在進行的變更，是了解其他人感興趣的內容以及觀察整個專案流程的好方法。

對專案的貢獻是通過 GitHub Pull Request 進行的。您可以加入 pr-subscribers-* GitHub 團隊之一，以訂閱程式碼庫區域的通知。此 mapping 指示哪個團隊與儲存庫中的特定路徑相關聯。

您還可以訂閱您感興趣的子專案的「commits」郵件列表，例如 llvm-commits、cfe-commits 或 lldb-commits。

遺失的功能和錯誤通過我們的 GitHub issue tracker 進行追蹤並分配標籤。我們建議活躍的開發者監控傳入的問題。您可以加入 issue-subscribers-* 團隊之一，以訂閱特定組件的通知。您也可以訂閱 llvm-bugs 電子郵件列表，以追蹤整個專案中發生的錯誤和增強功能。我們非常感謝積極主動地捕捉其組件中的傳入錯誤並及時處理的人員。

請注意，所有公開的 LLVM 郵件列表和 Discourse 論壇都是公開且已歸檔的，並且保密或不公開的聲明將不被尊重。

製作和提交補丁

在製作補丁以供審查時，目標是使審查者盡可能輕鬆地閱讀它。因此，我們建議您

  1. 針對 git main 而不是分支，也不是舊版本的 LLVM 製作補丁。這使得應用補丁變得容易。有關如何從 git 克隆的信息，請參閱 入門指南。

  2. 同樣地，補丁應在生成後盡快提交。如果底層程式碼在補丁創建時和應用時之間發生變更，則舊補丁可能無法正確應用。

  3. 創建補丁後，為其創建一個 GitHub Pull Request（或在適用的情況下直接提交）。

提交補丁時，請勿在補丁本身中添加保密或不公開聲明。這些聲明與 LLVM 許可條款衝突，並可能導致您的貢獻被排除在外。

電子郵件地址

LLVM 專案使用電子郵件與 GitHub 平台之外的貢獻者溝通他們過去的貢獻。主要是，我們的 buildbot 基礎架構使用電子郵件聯繫貢獻者，告知他們構建和測試失敗的情況。

因此，LLVM 社群要求貢獻者在其 GitHub 提交中關聯一個公開的電子郵件地址，因此請確保在您的 帳戶設定 中停用「保持我的電子郵件地址私密」。

程式碼審查

LLVM 有程式碼審查政策。程式碼審查是提高軟體品質的一種方法。有關 LLVM 程式碼審查流程的更多信息，請參閱 LLVM 程式碼審查政策與實踐。

做出可能造成重大變更

當升級到工具的較新版本時，請協助通知使用者和供應商潛在的中斷。例如，棄用預計將在未來版本中移除的功能、移除已棄用的功能、將診斷從警告升級為錯誤、切換重要的預設行為，或任何其他認為值得提高警覺的潛在破壞性情況。對於此類變更，應執行以下操作

警告

Phabricator 已被棄用，並且處於唯讀模式，對於新的程式碼貢獻，請使用 GitHub Pull Request。本節包含需要更新的舊信息。

  • 在執行變更的程式碼審查時，請將任何適用的「供應商」群組添加到審查中，以引起他們的注意。這些群組的目的是讓供應商提前注意到正在考慮潛在的破壞性變更，但尚未被接受。供應商可以對變更提供早期測試反饋，以提醒我們注意不可接受的破壞。目前的供應商群組列表為

    有興趣加入供應商群組的人員可以通過點擊 Phabricator 中供應商「成員」頁面上的「加入專案」連結來加入。

  • 將變更提交到儲存庫時，請將有關潛在重大變更的適當信息添加到專案發行說明的 Potentially Breaking Changes 部分。發行說明應包含有關變更內容、潛在破壞性內容以及任何適合與使用者分享的程式碼範例、連結和動機的信息。這有助於使用者了解升級到該版本可能遇到的問題。

  • 在變更已提交到儲存庫後，應將發行說明中描述的潛在破壞性變更發佈到 Discourse 上的 公告 頻道。該貼文應標記 potentially-breaking 標籤和特定於專案的標籤（例如 clang、llvm 等）。這是另一種機制，我們可以通過它向使用者發佈有關潛在破壞性變更的發行前通知。它是加入「供應商」群組的低流量替代方案。要自動接收帶有 potentially-breaking 標籤的新公告通知，請轉到 Discourse 中的使用者偏好設定頁面，並將該標籤添加到 Notifications->Tags 下的監看類別之一。

維護者

LLVM 專案旨在快速發展功能，同時持續保持發行就緒狀態。為了實現這一目標，專案需要志願者願意做一些不那麼光鮮亮麗的工作，以確保我們生產穩健、高品質的產品。

維護者就是這些志願者；他們是定期貢獻者，自願承擔程式碼貢獻之外的額外社群責任。社群成員可以在各個專案根目錄下的 Maintainers.rst 檔案中找到專案的活躍和非活躍維護者。

維護者自願在專案的某個領域內承擔以下共同責任

  • 確保提交的內容獲得高品質的審查，由維護者或其他人員進行，

  • 協助確認和評論問題，

  • 通過與其他維護者（和其他審查者）協作來調解程式碼審查分歧，以就如何最好地處理有爭議的變更達成共識，

  • 積極參與相關的 RFC，

  • 協助發行經理進行向後移植和其他與發行相關的活動，

  • 成為需要協助的貢獻者的聯絡點（回答 Discord/Discourse 上的問題或舉辦辦公時間）。

monorepo 中的每個頂級專案都將指定一名或多名主要維護者，負責確保滿足該專案的社群需求。此角色與任何其他維護者角色類似，只是責任範圍涵蓋整個專案，而不是專案內的有限區域。如果您無法聯繫到維護者，或者不知道該聯繫哪個維護者，則主要維護者始終是個不錯的選擇。如果一個專案沒有活躍的主要維護者，則該專案可能是從 monorepo 中移除的合理候選者。應在 Discourse 上發起討論，以尋找新的、活躍的主要維護者，或確定是否應終止該專案。

所有具有 LLVM 專案提交權限的貢獻者都有資格成為維護者。但是，我們正在尋找可以承諾以下事項的人員

  • 每月大部分時間都參與其職責，

  • 確保他們及其互動的社群成員遵守 LLVM 社群行為準則，以及

  • 執行這些職責至少三個月。

我們認識到優先事項會轉移、工作會變更、倦怠是真實存在的、長時間的假期是一種祝福，人們的生活通常很複雜。因此，我們希望盡可能減少某人成為維護者或辭去維護者的摩擦。

要成為新的維護者，您可以通過發佈 PR 將自己添加到您自願負責的區域來自願加入。或者，現有的維護者可以通過發佈 PR 來提名您，但被提名者必須明確接受 PR，以明確表示他們同意在提議的區域內自願服務。只要同一專案中至少有一位維護者認可其履行職責的能力，並且社群沒有提出明確的反對意見，PR 就會被接受。

要辭去維護者職務，您可以將您的名字移至專案的 Maintainers.rst 檔案的「非活躍維護者」部分，或完全刪除您的名字；無需 PR 審查。此外，任何在一段時間內沒有積極履行其職責的維護者，都可以由該專案中的另一位活躍維護者在徵得該專案中另一位活躍維護者的同意後，移至「非活躍維護者」部分。如果一個專案只有一位活躍維護者，請在 Discourse 上發佈帖子，徵求更廣泛的社群對移除和專案未來方向的反饋意見。但是，請在移除之前與非活躍維護者討論情況，以避免意外的溝通失誤。如果無法聯繫到非活躍維護者，則無需與他們討論。辭去或被移除維護者職務是正常的，並且不會阻止某人在未來恢復其作為維護者的活動。

要恢復作為維護者的活動，您可以發佈 PR，將您的名字從 Maintainers.rst 檔案的「非活躍維護者」部分移至活躍維護者列表。由於志願者之前已被接受，因此只要同一專案中至少有一位維護者批准 PR，並且社群沒有提出明確的反對意見，他們就會被重新接受。

測試案例

開發者需要為已修復的任何錯誤和新增的任何新功能創建測試案例。以下是一些使您的測試案例獲得批准的技巧

  • 所有功能和回歸測試案例都添加到 llvm/test 目錄中。應選擇適當的子目錄（有關詳細信息，請參閱 測試指南）。

  • 測試案例應使用 LLVM 組合語言 編寫。

  • 測試案例，尤其是回歸測試，應通過 bugpoint 或手動盡可能減少。將整個失敗的程式放入 llvm/test 中是不可接受的，因為這會給所有開發者帶來 time-to-test 負擔。請保持簡短。

  • 避免添加指向整個社群無法訪問的資源的連結，例如指向私有錯誤追蹤器、公司內部文件等的連結。相反，添加足夠的註解到測試中，以提供這些連結背後的背景資訊。

請注意，llvm/test 和 clang/test 僅用於回歸和小功能測試。更廣泛的測試案例（例如，整個應用程式、基準測試等）應添加到 llvm-test 測試套件中。llvm-test 套件用於覆蓋率（正確性、性能等）測試，而不是功能或回歸測試。

發行說明

LLVM 中的許多專案通過發行說明向使用者傳達重要的變更，發行說明通常位於專案的 docs/ReleaseNotes.rst 中。專案中面向使用者或使用者可能希望了解的變更，應由作者或程式碼審查者酌情添加到專案的發行說明中，最好作為提交變更的一部分。通常需要添加發行說明的變更範例（此列表並非詳盡無遺）

  • 新增、移除或修改命令行選項。

  • 新增、移除或重新分組診斷訊息。

  • 修復可能對使用者造成重大影響的錯誤（請連結到錯誤資料庫中修復的問題）。

  • 新增或移除具有廣泛影響或啟用新程式設計範例的優化。

  • 修改 C 穩定 API。

  • 通知使用者有關預計在未來版本中進行的潛在破壞性變更，例如移除已棄用的功能。在這種情況下，發行說明應添加到註釋的 Potentially Breaking Changes 部分，並提供足夠的信息和範例來證明潛在的破壞性。此外，此部分中的任何新條目都應在 Discourse 上的 公告 頻道中發佈。有關更多詳細信息，請參閱 做出可能造成重大變更。

如果程式碼審查者認為在執行程式碼審查時需要發行說明，則鼓勵他們要求提供發行說明。

品質

任何變更在提交到主要開發分支之前必須滿足的最低品質標準是

  1. 程式碼必須遵守 LLVM 程式碼規範。

  2. 程式碼必須在至少一個平台上乾淨地編譯（無錯誤，無警告）。

  3. 錯誤修復和新功能應 包含測試案例，以便我們知道修復/功能在未來是否會回歸。

  4. 程式碼必須通過 llvm/test 測試套件。

  5. 程式碼不得在 llvm-test 的合理子集上引起回歸，其中「合理」取決於貢獻者的判斷和變更的範圍（侵入性更強的變更需要更多測試）。合理的子集可能是類似「llvm-test/MultiSource/Benchmarks」的內容。

  6. 確保原始碼和測試檔案中的連結指向公開可用的資源，並且主要用於添加額外信息，而不是提供關鍵背景資訊。周圍的註解應足以提供這些連結背後的背景資訊。

此外，提交者有責任解決未來發現的由該變更引起的任何問題。例如

  • 程式碼應在所有支援的平台上乾淨地編譯。

  • 變更不應在 llvm-test 套件中引起任何正確性回歸，並且不得引起任何重大的性能回歸。

  • 變更集不應導致 LLVM 工具的性能或正確性回歸。

  • 變更不應導致 LLVM 在所有適用的目標平台上編譯的程式碼的性能或正確性回歸。

  • 您需要解決由您的變更引起的任何 GitHub Issue。

我們希望在提交之前處理此問題，但理解並非每次提交都可以測試所有這些問題。我們的 build bot 和夜間測試基礎架構通常會發現這些問題。如果包含您的提交的一組提交導致失敗，Build bot 將直接通過電子郵件通知您。您需要檢查 build bot 訊息以查看是否是您的錯誤，如果是，則修復損壞。

違反這些品質標準的提交（例如，非常損壞）可能會被還原。當變更阻止其他開發者取得進展時，這是必要的。開發者可以在問題修復後重新提交變更。

提交訊息

儘管我們不強制執行提交訊息的格式，但我們建議您遵循這些準則，以幫助審查、在日誌中搜尋、電子郵件格式等等。這些準則與其他開源專案使用的規則非常相似。

最重要的是，訊息的內容應仔細編寫，以傳達變更的基本原理（而不會過於深入細節）。它也應避免含糊不清或過於具體。例如，「位元未正確設定」會讓審查者想知道哪些位元，以及為什麼它們不正確，而「正確設定 TargetInfo 中的溢出位元」幾乎傳達了變更的所有內容。

以下是有關訊息本身格式的一些準則

  • 將提交訊息分為標題和正文，並以空行分隔。

  • 如果您不是原始作者，請確保提交的「作者」屬性設定為原始作者，而「提交者」屬性設定為您自己。您可以使用類似於 git commit --amend --author="John Doe <jdoe@llvm.org>" 的命令來更正作者屬性（如果它不正確）。有關更多信息，包括專案遷移到 git 之前我們用於歸屬的方法，請參閱 變更歸屬。

    在極少數情況下，當有多位作者時，請使用 git 標籤「Co-authored-by:」列出其他作者。

  • 標題應簡潔。由於所有提交都通過電子郵件發送到列表，並以第一行作為主題，因此不贊成使用長標題。簡短的標題在 git log 中也看起來更好。

  • 當變更僅限於程式碼的特定部分（例如後端或優化 pass）時，習慣上在該行的開頭以方括號添加標籤。例如，「[SCEV] …」或「[OpenMP] …」。這有助於電子郵件過濾器和搜尋以進行提交後審查。

  • 正文（如果存在）應與標題之間用空行分隔。

  • 正文應簡潔但具有解釋性，包括完整的理由。除非理解變更需要，否則範例、程式碼片段和詳細信息應留給錯誤評論、Web 審查或郵件列表。

  • 文字格式和拼寫應遵循與文件和程式碼內註解相同的規則，例如大寫、句號等。

  • 如果提交是對另一個最近提交的補丁的錯誤修復，或是補丁的還原或重新應用，請包含先前相關提交的 git 提交哈希值。這可以像「還原提交 NNNN，因為它導致 PR#」一樣簡單。

  • 如果補丁已審查，請添加指向其審查頁面的連結，如 此處 所示。如果補丁修復了 GitHub Issues 中的錯誤，我們鼓勵添加對已關閉問題的引用，如 此處 所述。

  • 還可以將其他元數據添加到提交訊息中以自動化流程，包括下游消費者。此元數據可以包括指向整個社群無法訪問的資源的連結。但是，此類連結和/或元數據不應用於代替使提交訊息具有自我解釋性。請注意，此類非公開連結不應包含在提交的程式碼中。

對於輕微違反這些建議的情況，社群通常傾向於提醒貢獻者此政策，而不是還原。輕微的更正和遺漏可以通過發送回覆到提交郵件列表來處理。

補丁回退政策

作為一個社群，我們非常重視保持程式碼樹尖端的良好狀態，同時允許快速迭代開發。因此，與其他一些開源專案相比，我們傾向於更頻繁地使用還原來保持樹的健康，並且我們的規範也略有不同。

如果有人還原了您的變更，您應該如何回應？

  • 請記住，補丁被還原是正常且健康的。補丁被還原並不一定意味著您做錯了什麼。

  • 我們鼓勵明確感謝還原補丁的人代表您執行了任務。

  • 如果您需要更多信息來解決問題，請在原始提交線程中與還原補丁的作者聯繫。

您應該在何時還原自己的變更？

  • 每當您發現變更存在嚴重問題時，都應還原它。我們強烈建議「還原到綠色」，而不是「向前修復」。我們鼓勵先還原，離線調查，然後重新應用修復後的補丁 - 如果有必要，可以在另一輪審查後進行。

  • 如果您以無法快速修復的方式破壞了 buildbot，請還原。

  • 如果在提交線程中報告了證明問題的測試案例，請還原並離線調查。

  • 如果您收到大量的 提交後審查 反饋，請還原並在重新提交之前處理所述反饋。（可能在另一輪審查之後。）

  • 如果另一位貢獻者要求您還原，請還原並離線討論請求的優點（除非這樣做會進一步破壞程式碼樹尖端的穩定性）。

您應該在何時還原其他人的變更？

  • 一般而言，如果作者自己會按照這些準則還原變更，我們鼓勵其他貢獻者為作者提供方便而這樣做。這是我們的規範與其他規範不同的主要情況之一；我們通常認為還原是開發的正常部分。我們不期望貢獻者始終可用，並且保證有問題的補丁將被還原，並且我們可以在下次有機會時返回處理它，這使得這種做法成為可能。

圍繞還原有哪些期望？

  • 請運用您最佳的判斷力。如果您不確定，請在提交線程上發起電子郵件尋求協助。我們並不是要枚舉所有情況，而是提供一組準則。

  • 您應該確定還原變更可以提高程式碼樹尖端的穩定性。有時，還原一系列變更中的一個變更可能會使情況變得更糟，而不是改善情況。我們期望合理的判斷，以確保正在還原正確的補丁或一組補丁。

  • 還原提交的提交訊息應說明還原補丁的原因。

  • 習慣上回覆原始提交電子郵件，提及還原。這既可以通知原始作者他們的補丁已被還原，也有助於其他關注 llvm-commits 的人追蹤上下文。

  • 理想情況下，您應該準備好公開可重現的測試案例以供分享。在可能的情況下，我們鼓勵在提交線程或 PR 中分享測試案例。我們鼓勵還原者盡量減少測試案例並在實際情況下刪除依賴項。即使在還原您自己的補丁時也是如此；記錄其他可能關注的人員的原因至關重要。

  • 如果沒有至少承諾為補丁作者提供調試根本問題的方法，則還原被認為是不合理的。如果出現由於某些原因（例如，需要補丁作者無法訪問的硬體、內部工作負載編譯時間的急劇回歸等）而無法共享公共重現器的情況，則還原者應積極主動地與補丁作者合作以調試和測試候選補丁。

  • 還原應在合理的時間內完成。兩小時前提交的變更可以在沒有事先討論的情況下還原。兩年前提交的變更不應還原。確切的過渡點很難說，但可能在樹狀結構中的幾天內。如果您不確定，我們鼓勵您回覆提交線程，給作者一點時間回應，然後在作者似乎沒有積極回應的情況下繼續還原。

  • 重新應用還原的補丁時，應更新提交訊息以指示已解決的問題以及如何解決的。

取得提交權限

一旦您有 3 個或更多合併的 pull request，您可以使用此連結 <https://github.com/llvm/llvm-project/issues/new?title=Request%20Commit%20Access%20For%20%3Cuser%3E&body=%23%23%23%20Why%20Are%20you%20requesting%20commit%20access%20?>`_ 提交 issue 並請求提交權限。將標題中的 <user> 字串替換為您的 github 使用者名稱，並在 issue 描述中說明您請求提交權限的原因。建立 issue 後，您需要獲得兩位目前的貢獻者的支持，然後才能授予提交權限。

您提交的補丁的審查者將在創建 issue 後自動抄送。最常見的是，這些審查者將提供必要的批准，但來自其他 LLVM 提交者的批准也是可以接受的。審查應用程式的人員正在確認您確實已提交三個補丁，並且根據在這些審查和 LLVM 社群其他地方的互動，他們對您遵守我們的開發者政策和行為準則沒有任何疑慮。

如果獲得批准，GitHub 邀請將發送到您的 GitHub 帳戶。如果您沒有收到來自 GitHub 的通知，請直接轉到 邀請連結。接受邀請後，您將獲得提交權限。

在獲得提交權限之前，通常的做法是請求具有提交權限的人員代表您提交。執行此操作時，請提供您希望在提交的 Author 屬性中使用的名稱和電子郵件地址。

為了外部追蹤目的，提交的變更會在提交完成後很快反映在提交郵件列表上（例如 llvm-commits）。請注意，這些郵件列表是經過審核的，並且大型提交通常需要審核者批准電子郵件，因此如果提交沒有立即出現在存檔中，請不要擔心。

如果您最近被授予提交權限，則以下政策適用

  1. 您被授予對 LLVM 所有部分的 批准後提交 權限。有關如何獲得補丁批准的信息，請參閱 LLVM 程式碼審查政策與實踐。獲得批准後，您可以自行提交。

  2. 您可以在未經批准的情況下提交您認為顯而易見的修補程式。這顯然是一個主觀的決定——我們只是期望您運用良好的判斷力。範例包括：修復建置錯誤、還原明顯損壞的修補程式、文件/註解變更以及任何其他次要變更。避免提交僅限格式或僅限空白字元的變更，除非您計劃對該程式碼進行後續變更。此外，盡量將格式或空白字元變更與功能變更分開，可以先修正格式（理想情況下）或之後再修正。此類變更應高度局部化，並且提交訊息應清楚說明該提交不打算變更功能，通常會聲明它是 NFC。

  3. 您可以未經批准提交您貢獻或維護的 LLVM 部分（即，已被指派責任的部分）的修補程式，但前提是此類提交不得破壞建置。這是一個「信任但驗證」的政策，此性質的提交會在提交後進行審查。

  4. 多次違反這些政策或單次嚴重違規可能會導致撤銷提交權限。

在任何情況下，您的變更仍然需要經過程式碼審查（在提交之前或之後，取決於變更的性質）。我們鼓勵您也審查其他人的修補程式，但您並非必須這樣做。

進行重大變更

當開發人員開始一個旨在貢獻回 LLVM 的重大新專案時，他們應盡可能在 LLVM Discourse 論壇上發布文章告知社群。這樣做的原因是為了

  1. 讓社群了解 LLVM 未來的變更，

  2. 避免重複作業，防止多方從事同一件事卻不知情，以及

  3. 確保在進行任何重大工作之前，針對擬議工作周圍的任何技術問題進行討論和解決。

LLVM 的設計經過仔細控制，以確保所有組件都能良好地整合在一起，並盡可能保持一致。如果您計劃對 LLVM 的運作方式進行重大變更，或想新增一個主要的新擴充功能，最好在開始工作之前與開發社群達成共識。

一旦新功能的設計定案，工作本身應以一系列漸進式變更完成，而不是以長期開發分支的形式進行。

漸進式開發

在 LLVM 專案中，我們將所有重大變更都作為一系列漸進式修補程式來進行。我們非常不喜歡巨大的變更或長期開發分支。長期開發分支有許多缺點

  1. 分支必須定期將主線合併到其中。如果分支開發和主線開發發生在相同的程式碼片段中，解決合併衝突可能會花費大量時間。

  2. 社群中的其他人傾向於忽略分支上的工作。

  3. 當分支合併回主線時產生的巨大變更極難進行程式碼審查。

  4. 分支不會由我們的每日測試基礎架構進行例行測試。

  5. 以單體式大型變更開發的變更通常在完成整個變更集之前都無法運作。將其分解為一組較小的變更會增加任何工作被提交到主要儲存庫的機率。

為了應對這些問題，LLVM 使用漸進式開發風格，我們要求貢獻者在進行大型/侵入性變更時遵循此做法。一些提示

  • 大型/侵入性變更通常在進行重大變更之前需要一些次要變更（例如，API 清理等）。這些種類的變更通常可以在重大變更完成之前完成，並且與該工作無關。

  • 如果可能，其餘相互關聯的工作應分解為不相關的變更集。完成此操作後，定義第一個增量，並就變更的最終目標達成共識。

  • 集合中的每個變更都可以是獨立的（例如，修復錯誤），或是朝著開發目標邁進的計劃系列變更的一部分。

  • 每個變更都應盡可能保持小規模。這簡化了您的工作（成為邏輯進程）、簡化了程式碼審查，並降低了您收到有關變更負面回饋的可能性。小的增量也有助於維護高品質的程式碼庫。

  • 通常，重大變更的獨立先決條件是新增一個新的 API，並逐漸將用戶端遷移到使用新的 API。每次使用新 API 的變更通常都是「顯而易見的」，並且可以在未經審查的情況下提交。一旦新的 API 到位並被使用，就更容易替換 API 的底層實作。此實作變更在邏輯上與 API 變更分開。

如果您有興趣進行重大變更，並且對此感到擔憂，請務必先討論變更/收集共識，然後詢問進行變更的最佳方法。

變更歸屬

當貢獻者向 LLVM 專案提交修補程式時，具有提交權限的其他開發人員可能會在適當的時候（根據程式碼審查的進展等）為作者提交修補程式。這樣做時，務必保留對貢獻者的正確貢獻歸屬。但是，我們不希望原始碼中充斥著隨機的歸屬「此程式碼由 J. Random Hacker 編寫」（這很吵雜且令人分心）。實際上，修訂控制系統會完美地記錄誰變更了什麼，而 CREDITS.txt 檔案則描述了更高層次的貢獻。如果您為其他人提交修補程式，請按照 提交訊息 章節中概述的簡單方式進行變更歸屬。總之，請勿將貢獻者姓名新增到原始碼中。

此外，除非其他人已將修補程式提交給專案，或者您已被授權代表他們提交修補程式（您們一起工作並且您的公司授權您貢獻修補程式等），否則請勿提交其他人撰寫的修補程式。作者應先將其提交到相關專案的提交清單、開發清單或 LLVM 錯誤追蹤器元件。如果有人私下向您發送修補程式，請鼓勵他們先將其提交到適當的清單。

我們之前的版本控制系統 (subversion) 並未像 git 那樣區分作者和提交者。因此，較舊的提交使用了不同的歸屬機制。以前的方法是在提交訊息的單獨一行中包含「Patch by John Doe.」，並且有自動化流程依賴於此格式。

封鎖

封鎖的目標是保護社群中的人們免於與持續不尊重 LLVM 專案空間中的LLVM 社群行為準則的人互動。任何形式的貢獻（提取請求、問題報告、論壇文章等）都需要與社群互動。因此，我們不接受來自被封鎖個人的任何形式的直接貢獻。

間接貢獻僅在有人完全擁有此類貢獻的所有權，並且他們負責與社群就該貢獻進行的所有相關互動時才被允許。

當您不確定在特定情況下該如何做時，請聯繫 conduct@llvm.org 尋求建議。

IR 向後相容性

當 IR 格式必須變更時，請記住我們嘗試保持一定的向後相容性。這些規則旨在在 LLVM 使用者的便利性和不給 LLVM 開發人員帶來沉重負擔之間取得平衡

  • 文字格式不向後相容。我們不會太頻繁地變更它，但沒有具體的承諾。

  • 對 IR 的新增和變更應反映在 test/Bitcode/compatibility.ll 中。

  • 目前的 LLVM 版本支援載入自 3.0 版以來的任何位元碼。

  • 在每個 X.Y 版本發布後，compatibility.ll 必須複製到 compatibility-X.Y.ll。對應的位元碼檔案應使用 X.Y 建置組裝，並作為 compatibility-X.Y.ll.bc 提交。

  • 較新的版本可以忽略較舊版本的功能，但它們不能錯誤編譯它們。例如，如果 nsw 永遠被其他東西取代，放棄它將是升級 IR 的有效方法。

  • 偵錯元資料很特殊，因為它目前在升級期間被丟棄。

  • 非偵錯元資料被定義為可以安全丟棄，因此升級它的有效方法是丟棄它。這對使用者不太友善，並且需要付出更多努力，但沒有做出任何承諾。

C API 變更

  • 穩定性保證：一般而言，C API 是「盡力而為」的穩定性。這意味著我們盡一切努力保持 C API 的穩定性，但這種穩定性將受到介面的抽象性和它包裝的 C++ API 的穩定性的限制。實際上，這意味著諸如「建立偵錯資訊」或「建立此類型的指令」之類的事情可能不如「取得此 IR 檔案並為我目前的機器進行 JIT」穩定。

  • 發布穩定性：我們不會在發布分支上破壞 C API，除非修補程式會進入該分支，但我們會修復意外的 C API 破壞，以保持發布與之前和之後的發布一致。

  • 測試：與任何其他修補程式一樣，C API 的修補程式預計會附帶測試。

  • 將新事物納入 API：如果 LLVM 子元件已經包含 C API，則擴充該 C API 是可以接受的。目前沒有 C API 的子元件新增 C API 需要在 LLVM Discourse 論壇上討論設計和可維護性回饋，然後才能實作。

  • 文件：任何對 C API 的變更都必須記錄在發布說明中，以便不關注專案的外部使用者清楚了解 C API 如何變更和演進。

更新工具鏈需求

我們打算隨著時間的推移要求更新的工具鏈。這意味著 LLVM 的程式碼庫可以使用標準化後更新版本的 C++。要求更新的工具鏈來建置 LLVM 對於那些建置 LLVM 的人來說可能是痛苦的；因此，它只會透過以下流程完成

  • 一般目標是至少支援過去 3 年的 LLVM 和 GCC 版本。此基於時間的準則並非嚴格：我們可能會支援更舊的編譯器，或決定支援更少的版本。

  • RFC 會發送到 LLVM Discourse 論壇

    • 詳細說明版本增加的優點（例如，LLVM 應使用哪些較新的 C++ 語言或程式庫功能；避免特定編譯器版本中的錯誤編譯等）。

    • 詳細說明重要平台上的缺點（例如，Ubuntu LTS 狀態）。

  • 一旦 RFC 達成共識，請更新 CMake 工具鏈版本檢查以及入門指南。這為編譯 LLVM 的開發人員提供了更柔和的轉換路徑，因為可以使用 CMake 標誌將錯誤變成警告。這是重要的一步：LLVM 仍然沒有需要新工具鏈的程式碼，但很快就會有。如果您編譯 LLVM 但不閱讀論壇，我們應該告訴您！

  • 確保至少有一個 LLVM 發布版本具有此軟錯誤。並非所有開發人員都編譯 LLVM 最新程式碼。這些與發布版本相關的開發人員也應該被告知即將發生的變更。

  • 在所述 LLVM 發布版本分支後，將軟錯誤變成硬錯誤。

  • 更新程式碼標準以允許我們在 RFC 中明確批准的新功能。

  • 開始在 LLVM 的程式碼庫中使用新功能。

這是一個 範例 RFC 和 對應的變更。

使用 CI 系統

LLVM 專案的主要持續整合 (CI) 工具是 LLVM Buildbot。它使用不同的建置器來涵蓋各種子專案和配置。建置會在不同的工作站上執行。建置器和工作站由社群成員配置和提供。

Buildbot 追蹤主分支和發布分支上的提交。這意味著修補程式在合併到這些分支後（又名合併後測試）會被建置和測試。這也意味著偶爾破壞建置是可以接受的，因為期望貢獻者使用每種可能的配置來建置和測試他們的修補程式是不合理的。

如果您的提交破壞了建置

  • 盡快修復建置，因為這可能會阻礙其他貢獻者或下游使用者。

  • 如果您需要更多時間來分析和修復錯誤，請還原您的變更以解除對其他人的封鎖。

如果其他人破壞了建置並且這阻礙了您的工作

  • 在 GitHub 的程式碼審查中發表評論（如果可用）或通過電子郵件聯繫作者，說明問題以及這如何影響您。新增指向損壞的建置和錯誤訊息的連結，以便人們可以了解問題。

  • 如果這阻礙了您的工作，請還原提交，請參閱 revert_policy 。

如果建置/工作站永久損壞

  • 第一步：聯繫工作站的所有者。您可以在工作站標籤中建置頁面上找到工作站管理員的姓名和聯絡資訊

    _images/buildbot_worker_contact.png

  • 第二步：如果所有者沒有回應或修復工作站，請升級至 BuildBot 主機的維護者 Galina Kostanova。

  • 第三步：如果 Galina 無法幫助您，請升級至 基礎架構工作組。

將新組件引入 LLVM

LLVM 社群是一個充滿活力和令人興奮的地方，我們希望包容新專案並促進新社群，並加強產業和學術界之間的合作。

話雖如此，我們需要在包容新想法和人員與新程式碼所需的持續維護成本之間取得平衡。因此，我們針對將主要新組件引入 LLVM 世界制定了一般支援政策，具體取決於所需的詳細程度和責任。核心專案需要比週邊專案更高程度的審查，後者可能會有其他差異。

但是，這實際上僅旨在涵蓋我們看到的常見情況：不同的情況是不同的，我們也願意討論不尋常的情況 - 只需在 LLVM Discourse 論壇上啟動 RFC 討論串即可。

新增新目標

LLVM 非常歡迎新目標，即使是實驗性的目標也是如此，但是在新增大量新程式碼時可能會出現許多問題，並且後端通常會批量新增。新目標需要與編譯器的其他核心部分相同的支援等級，因此它們涵蓋在我們的支援政策的核心層級中。

我們發現，先提交大量新程式碼，然後嘗試在樹狀結構中修復新出現的問題是有問題的，原因有很多。由於這些原因，新目標始終以實驗性方式新增，直到它們可以被證明穩定，然後再移至非實驗性。

這兩個類別之間的差異是

  • 實驗性目標預設不會建置（它們需要在 CMake 時顯式啟用）。

  • 僅當啟用實驗性目標時才會出現的測試失敗、錯誤和建置中斷，是由於與目標無關的變更引起的，則由目標背後的社群負責修復。

後端以 實驗性 模式向上游的基本規則是

  • 每個目標都必須至少有一位維護者。Maintainers.rst 檔案必須作為第一次合併的一部分進行更新。這些維護者確保對目標的變更得到審查，並引導整體工作。

  • 目標背後必須有一個活躍的社群。此社群將透過提供建置機器人、修復錯誤、回答 LLVM 社群的問題並確保新目標不會破壞任何其他目標或通用程式碼來協助維護目標。預計在目標程式碼的整個生命週期內都會持續這種行為。

  • 程式碼必須沒有爭議性問題，例如，IR 行為方式或應由前端形成的重大變更，除非社群的大多數人透過重構 (IR 標準) 在合併新目標變更之前，依照IR 向後相容性達成協議。

  • 程式碼符合本開發人員政策文件中規定的所有政策，包括許可證、專利和程式碼標準。

  • 目標應具有關於其運作方式（ISA、ABI 等）的合理文件，或公開可用的模擬器/硬體（免費或足夠便宜） - 最好兩者兼具。這使開發人員能夠驗證假設、了解約束並審查可能影響目標的程式碼。

此外，將後端升級為 正式 的規則是

  • 目標必須已解決所有其他最低要求，並且在樹狀結構中穩定至少 3 個月。此冷卻期是為了確保後端和目標社群能夠在可預見的未來承受持續的上游開發。

  • 目標的程式碼必須已完全適應此政策以及程式碼標準。為進入實驗性模式而做出的任何例外都必須在成為正式版之前修復。

  • 測試涵蓋範圍需要廣泛且編寫良好（小型測試，文件完善）。建置目標 check-all 必須在建置新目標的情況下通過，並且在適用的情況下，test-suite 也必須在至少一種配置中（公開演示，例如，透過建置機器人）通過且沒有錯誤。

  • 需要建立並積極維護公開的建置機器人，除非目標不需要額外的建置機器人（例如，check-all 涵蓋所有測試）。新目標的 CI 基礎架構越相關且越公開，LLVM 社群就越會接受它。

要 繼續 作為受支援的正式目標

  • 維護者必須在目標的整個生命週期內繼續遵循這些規則。持續違反上述規則和政策可能會導致從程式碼庫中完全移除目標。

  • 支援、文件或測試涵蓋範圍的退化將使目標成為其他目標的麻煩，並被視為棄用並最終移除的候選目標。

從本質上講，這些規則對於目標獲得和保持其狀態是必要的，但也是定義位元腐爛的標記，並將用於清理樹狀結構中未維護的目標。

希望將新目標新增到 LLVM 的人必須遵循以下步驟

  1. 閱讀本節並確保您的目標符合所有要求。對於次要問題，您的社群將負責在初始合併後儘快做出所有必要的調整。

  2. 向 LLVM Discourse 論壇發送請求評論 (RFC)，描述您的目標以及它如何符合所有要求，以及已完成和需要完成哪些工作才能滿足正式目標要求。務必揭露任何和所有有爭議的問題、基礎程式碼中需要的變更、表格生成等。

  3. 一旦收到正面回應，LLVM 社群就可以開始審查實際的修補程式（但它們可以在之前準備好，以支援 RFC）。建立一系列 N 個修補程式，編號為「1/N」到「N/N」（確保 N 是實際數字，而不是字母「N」），以完成目標的基本結構。

  4. 初始修補程式應在 clang 和 LLVM 中新增文件、維護者和三元組支援。後續修補程式新增 TableGen 基礎架構以描述目標並將指令降低為組合語言。最後一個修補程式必須顯示目標可以透過廣泛的 LIT 測試（IR 到 MIR、MIR 到 ASM 等）正確降低。

  5. 有些修補程式可能會在其他修補程式之前獲得批准，但只有在所有修補程式都獲得批准後，整個集合才能一次合併。這是為了保證所有變更都作為一個單一區塊是好的。

  6. 在初始合併之後，目標社群可以停止對修補程式進行編號，並開始異步地處理目標以完成支援。他們仍然應該向在初始階段幫助他們的人尋求審查，以確保進度仍然一致。

  7. 一旦滿足所有正式要求（如上所述），維護者應透過向 LLVM Discourse 論壇發送另一個 RFC 來請求預設啟用目標。

將已建立的專案新增到 LLVM Monorepo

LLVM monorepo 是 LLVM 世界開發的中心點，擁有所有主要的 LLVM 組件，包括 LLVM 優化器和程式碼產生器、Clang、LLDB 等。一般而言，Monorepo 非常棒，因為它們允許對專案進行原子提交、簡化 CI，並使子社群更容易協作。

與新目標一樣，monorepo 中已有的大多數專案都被視為我們支援政策的核心層級。將事物新增到 LLVM monorepo 的負擔需要非常高 - 新增到此儲存庫的程式碼會被社群中的每個人檢出。因此，我們將組件保持在與「正式目標」相似的高標準，它們

  • 必須大致符合 LLVM 專案推進編譯器、語言、工具、執行階段等使命。

  • 必須符合本開發人員政策文件中規定的所有政策，包括許可證、專利、程式碼標準和行為準則。

  • 必須有一個活躍的社群來維護程式碼，包括已建立的維護者。

  • 應具有關於其運作方式的合理文件，包括高品質的 README 檔案。

  • 應具有 CI 以捕獲專案本身內部或由於底層 LLVM 依賴關係而導致的中斷。

  • 應具有沒有社群發現有爭議的問題的程式碼，或處於解決這些問題的明確路徑上。

  • 必須透過 LLVM RFC 流程提出，並經 LLVM 社群批准其新增 - 這最終調解了上述「應」關注事項的解決。

如果您有一個您認為新增到 LLVM monorepo 會很有意義的專案，請在 LLVM Discourse 論壇上啟動 RFC 主題，以啟動討論。此過程可能需要一些時間和迭代 - 請不要因此而氣餒或感到害怕！

如果您有一個您認為與 LLVM 一致的早期專案，請參閱「孵化新專案」部分。

孵化新專案

將新專案新增到 LLVM monorepo 的負擔有意地非常高，但這可能會對新的和創新的專案產生寒蟬效應。為了幫助促進這些專案，LLVM 支援一個「孵化器」流程，該流程更容易入門。它為潛在有價值的新頂層和子專案提供了空間，使其在擁有足夠的程式碼來證明其效用並發展社群之前達到臨界質量。這也允許已經有權限為 LLVM 保護傘下的專案做出貢獻的團隊之間進行協作。

可以考慮用於 LLVM 孵化器的專案符合以下標準

  • 必須大致符合 LLVM 專案推進編譯器、語言、工具、執行階段等使命。

  • 必須符合本開發人員政策文件中規定的許可證、專利和行為準則政策。

  • 必須具有記錄在案的章程和開發計劃，例如，以 README 檔案、使命宣言和/或宣言的形式。

  • 應符合程式碼標準、漸進式開發流程和其他期望。

  • 應對其希望最終培養的社群有所了解，並且應該有來自具有不同隸屬關係/組織的成員的興趣。

  • 應具有最終畢業成為 LLVM monorepo 內專用頂層或子專案的可行路徑。

  • 應包含專案處於「孵化狀態」且未包含在 LLVM 發布版本中的通知（例如，在專案 README 或網頁中）（請參閱下面建議的措辭）。

  • 必須透過 LLVM RFC 流程提出，並經 LLVM 社群批准其新增 - 這最終調解了上述「應」關注事項的解決。

話雖如此，專案無需任何程式碼即可開始，也無需完全建立社群！此外，孵化專案可能會經歷違反上述「應」準則的暫態，或在其他方面使其不適合直接包含在 monorepo 中的暫態（例如，尚未適當分解的依賴關係、利用尚未上游的實驗性組件或 API 等）。

獲得批准後，llvm-admin 群組可以授予新專案

  • LLVM Github 組織中的新儲存庫 - 但不是 LLVM monorepo。

  • 與其他 LLVM 論壇一起託管的新郵件清單、Discourse 論壇和/或 Discord 聊天。

  • 其他基礎架構整合可以在個案基礎上討論。

畢業到 mono-repo 將遵循現有的流程和標準，成為 monorepo 的一流部分。同樣，孵化專案最終可能會被淘汰，但尚未建立任何流程。如果何時出現這種情況，請在 LLVM Discourse 論壇上啟動 RFC 討論。

此流程非常新 - 請預期詳細資訊會變更，在 LLVM Discourse 論壇上詢問此事始終是安全的。

專案 README 和主要專案網頁的建議免責聲明

This project is participating in the LLVM Incubator process: as such, it is
not part of any official LLVM release.  While incubation status is not
necessarily a reflection of the completeness or stability of the code, it
does indicate that the project is not yet endorsed as a component of LLVM.