LLVM 開發者政策¶
簡介¶
本文件包含 LLVM 開發者政策,其中定義了專案對開發者及其貢獻的政策。本政策旨在消除因 LLVM 開發的分散性而可能產生的溝通不良、返工和混淆。通過明確說明政策,我們希望每個開發者都能夠事先知道在為 LLVM 做出貢獻時會發生什麼。本政策涵蓋所有 llvm.org 子專案,包括 Clang、LLDB、libc++ 等。
本政策還旨在實現以下目標
吸引使用者和開發者加入 LLVM 專案。
盡可能簡化貢獻者的工作。
盡可能保持主幹穩定。
讓專案貢獻者瞭解專案的版權、授權和專利政策。
本政策針對的是經常為 LLVM 做出貢獻的開發者。我們始終歡迎不常為 LLVM 做出貢獻的人提供一次性修補程式,但我們希望經常做出貢獻的開發者能夠滿足以下要求,以便 LLVM 保持高品質標準。
開發者政策¶
本節包含與經常為 LLVM 做出貢獻的開發者相關的政策。我們始終歡迎不常為 LLVM 做出貢獻的人提供一次性修補程式,但我們希望經常做出貢獻的開發者能夠滿足以下要求,以便 LLVM 為所有人保持盡可能高效的系統。經常為 LLVM 做出貢獻的開發者應滿足以下要求。
隨時掌握資訊¶
開發者應閱讀LLVM Discourse 論壇並訂閱感興趣的類別以接收通知,隨時掌握最新資訊。
關注他人所做的變更是瞭解其他人感興趣的內容以及觀察整個專案流程的好方法。
專案貢獻是透過 GitHub 拉取請求 來進行的。您可以加入其中一個 pr-subscribers-* GitHub 團隊,以訂閱程式碼庫特定區域的通知。這個 對應表 顯示了哪個團隊與儲存庫中的特定路徑相關聯。
您也可以訂閱您感興趣的子專案的「提交」郵件清單,例如 llvm-commits、cfe-commits 或 lldb-commits。
遺漏的功能和錯誤會透過我們的 GitHub 問題追蹤器 進行追蹤並標記標籤。我們建議活躍的開發人員監控新進的 issues。您可以加入其中一個 issue-subscribers-* 團隊,以訂閱特定元件的通知。您也可以訂閱 llvm-bugs 電子郵件清單,以追蹤整個專案中發生的錯誤和增強功能。我們非常感謝那些積極主動地在其元件中捕捉新進錯誤並及時處理的人。
請注意,所有公開的 LLVM 郵件清單和論壇都是公開的並會被存檔,並且我們無法尊重任何機密或不公開的聲明。
製作和提交修補程式¶
製作修補程式以供審查時,目標是盡可能讓審查者更容易閱讀。因此,我們建議您
根據 git 主線製作您的修補程式,而不是根據分支或舊版本的 LLVM。這使得應用修補程式變得容易。有關如何從 git 克隆的資訊,請參閱 入門指南。
同樣地,修補程式應在產生後盡快提交。如果在建立修補程式和應用修補程式之間底層程式碼發生更改,則舊的修補程式可能無法正確應用。
建立修補程式後,請為其建立 GitHub 拉取請求(或在適用的情況下直接提交)。
提交修補程式時,請勿在修補程式本身添加機密或不公開聲明。這些聲明與 LLVM 授權條款相衝突,可能會導致您的貢獻被排除。
程式碼審查¶
LLVM 有一套程式碼審查政策。程式碼審查是提高軟體品質的一種方法。有關 LLVM 程式碼審查流程的更多資訊,請參閱 LLVM 程式碼審查政策與實務。
進行可能造成破壞的變更¶
升級到新版工具時,請協助通知用戶和供應商潛在的影響。例如,棄用預計將在未來移除的功能、移除已棄用的功能、將診斷從警告升級為錯誤、切換重要的預設行為,或任何其他認為值得提高認識的潛在破壞性情況。對於此類變更,應執行以下操作
警告
Phabricator 已棄用,僅供唯讀模式使用,新的程式碼貢獻請使用 GitHub 拉取請求。本節包含需要更新的舊資訊。
在執行變更的程式碼審查時,請將任何適用的「供應商」群組新增至審查中,以便他們知悉。這些群組的目的是讓供應商及早注意到正在考慮但尚未被接受的潛在破壞性變更。供應商可以針對變更提供早期測試回饋,以提醒我們注意不可接受的破壞。
libc++ 供應商
有興趣加入供應商群組的人員,可以透過點選 Phabricator 中供應商「成員」頁面上的「加入專案」連結來加入。
將變更提交至儲存庫時,請在專案發行說明的「潛在破壞性變更」區段中新增有關潛在破壞性變更的適當資訊。發行說明應包含有關變更內容、潛在破壞性影響,以及任何適合與使用者分享的程式碼範例、連結和動機等資訊。這有助於使用者瞭解升級至該版本時可能遇到的問題。
在將變更提交至儲存庫後,應將發行說明中描述的潛在破壞性變更發佈至 Discourse 的「公告」頻道。這篇文章應標記為「潛在破壞性」標籤,以及專案特定的標籤(例如「clang」、「llvm」等)。這是我們可以向使用者發佈潛在破壞性變更的預先發佈通知的另一種機制。與加入「供應商」群組相比,這是一種流量較低的替代方案。若要自動收到帶有「潛在破壞性」標籤的新公告通知,請前往您在 Discourse 中的使用者偏好設定頁面,並將該標籤新增至「通知 -> 標籤」下的其中一個關注類別。
除了高品質的原始碼庫之外,LLVM 專案還仰賴其流程中的兩個特性來維持快速開發:程式碼審查與信任維護者的提交後審查相結合。兩者兼具是專案利用大多數人在大多數情況下都做正確事情,並且只有在他們確信自己正確時才會在沒有提交前審查的情況下提交修補程式這一事實的絕佳方式。
這樣做的訣竅是,專案必須確保提交的所有修補程式在提交後都經過審查:您不希望每個人都認為其他人會審查它,而導致修補程式未經審查。為了解決這個問題,我們對一部分程式碼有一個「負責人」的概念。程式碼負責人的唯一職責是確保他們負責的程式碼區域的提交經過適當的審查,無論是由他們自己還是由其他人審查。目前的程式碼負責人列表可以在 LLVM 原始碼樹根目錄下的 CODE_OWNERS.TXT 檔案中找到。
作為程式碼擁有者是一個不太起眼的角色,但對於專案的持續成功至關重要。由於人們會忙碌、興趣會改變,而且會發生意外狀況,程式碼所有權純粹是選擇性的,任何人都可以隨時選擇放棄他們的“頭銜”。目前,我們還沒有關於如何選舉成為程式碼擁有者的正式政策。
測試案例¶
開發人員必須為任何已修復的錯誤和新增的功能建立測試案例。以下是一些讓您的測試案例獲得批准的技巧
所有功能和回歸測試案例都會新增到
llvm/test
目錄中。應選擇適當的子目錄(詳情請參閱測試指南)。測試案例應使用 LLVM 組合語言 撰寫。
測試案例,尤其是回歸測試案例,應盡可能透過 bugpoint 或手動減少。將整個失敗的程式放入
llvm/test
是不可接受的,因為這會給所有開發人員帶來*測試時間*負擔。請保持簡短。避免新增指向整個社群無法使用的資源的連結,例如指向私人錯誤追蹤器、公司內部文件等的連結。請改為在測試中新增足夠的註釋,以提供這些連結背後的背景資訊。
請注意,llvm/test 和 clang/test 僅設計用於回歸測試和小型功能測試。更廣泛的測試案例(例如,整個應用程式、基準測試等)應新增到 llvm-test
測試套件中。llvm-test 套件用於覆蓋率(正確性、效能等)測試,而不是功能或回歸測試。
發行說明¶
LLVM 中的許多專案都透過發行說明向使用者傳達重要的變更,這些說明通常可以在專案的 docs/ReleaseNotes.rst
中找到。面向使用者的專案變更,或使用者可能希望知道的變更,應由作者或程式碼審閱者自行決定新增到專案的發行說明中,最好是在提交變更的過程中新增。通常需要新增發行說明的變更範例(此清單並非詳盡無遺)
新增、移除或修改命令列選項。
新增、移除或重新分組診斷訊息。
修復可能對使用者造成重大影響的錯誤(請連結到錯誤資料庫中修復的問題)。
新增或移除具有廣泛影響或啟用新程式設計範例的最佳化。
修改 C 穩定 API。
通知使用者未來版本中預計會發生的可能破壞性變更,例如移除已棄用的功能。在這種情況下,應將發行說明新增到說明的
潛在破壞性變更
章節中,並提供足夠的資訊和範例來說明潛在的破壞性。此外,應在 Discourse 的公告 頻道中公告此章節中的任何新增項目。如需更多詳細資訊,請參閱進行潛在破壞性變更。
鼓勵程式碼審閱者在執行程式碼審閱時,如果認為有必要,則要求提供發行說明。
品質¶
任何變更在被提交到主開發分支之前必須滿足的最低品質標準為:
程式碼必須遵守 LLVM 程式碼標準。
程式碼必須至少在一個平台上乾淨地編譯(沒有錯誤,沒有警告)。
錯誤修復和新功能應 包含測試案例,以便我們知道修復/功能是否在未來出現回歸。
程式碼必須通過
llvm/test
測試套件。程式碼不得在合理的 llvm-test 子集上造成回歸,其中「合理」取決於貢獻者的判斷和變更的範圍(更具侵入性的變更需要更多測試)。一個合理的子集可能是「
llvm-test/MultiSource/Benchmarks
」。確保原始碼和測試檔案中的連結指向公開可用的資源,並且主要用於添加額外資訊,而不是提供關鍵上下文。周圍的註釋應足以提供此類連結背後的上下文。
此外,提交者有責任解決未來發現的任何由變更引起的問題。例如:
程式碼應在所有支援的平台上乾淨地編譯。
變更不應在
llvm-test
套件中造成任何正確性回歸,並且不得造成任何重大的效能回歸。變更集不應對 LLVM 工具造成效能或正確性回歸。
變更不應對 LLVM 在所有適用目標上編譯的程式碼造成效能或正確性回歸。
您應該解決因您的變更而產生的任何 GitHub 問題。
我們希望在提交之前處理好這些問題,但我們理解不可能對每個提交都進行所有測試。我們的建置機器人和夜間測試基礎設施通常會發現這些問題。一個好的經驗法則是,在您的變更提交後的第二天檢查夜間測試人員是否有回歸。如果包含您的提交的提交組導致失敗,建置機器人會直接向您發送電子郵件。您應該檢查建置機器人的訊息,看看是否是您的錯誤,如果是,則修復錯誤。
違反這些品質標準的提交(例如,非常糟糕的提交)可能會被還原。當變更阻礙其他開發人員取得進展時,這是必要的。在問題得到解決後,開發人員可以重新提交變更。
提交訊息¶
雖然我們沒有強制執行提交訊息的格式,但我們希望您遵循這些準則,以幫助審閱、在日誌中搜尋、電子郵件格式化等等。這些準則與其他開放原始碼專案使用的規則非常相似。
最重要的是,訊息的內容應該仔細撰寫,以傳達變更的基本原理(不要過於詳細)。它也應該避免含糊不清或過於具體。例如,「位元設置不正確」會讓審閱者想知道是哪些位元,以及為什麼它們不正確,而「在 TargetInfo 中正確設置溢位位元」幾乎傳達了變更的所有內容。
以下是一些關於訊息本身格式的準則:
將提交訊息分為標題和正文,並以空行分隔。
如果您不是原始作者,請確保提交的「作者」屬性設置為原始作者,「提交者」屬性設置為您自己。您可以使用類似
git commit --amend --author="John Doe <jdoe@llvm.org>"
的指令來修正錯誤的作者屬性。有關更多資訊,包括專案遷移到 git 之前我們使用的歸屬方法,請參閱變更的歸屬。在極少數情況下,如果有多個作者,請使用git 標籤「共同作者:」來列出其他作者。
標題應該簡潔。由於所有提交都會以第一行為主題透過電子郵件發送到郵件清單,因此不建議使用過長的標題。簡短的標題在 git log 中看起來也比較好。
當變更僅限於程式碼的特定部分時(例如,後端或優化過程),習慣上在行首添加一個用方括號括起來的標籤。例如,「[SCEV] ...」或「[OpenMP] ...」。這有助於電子郵件過濾和搜尋提交後的審查。
如果有訊息正文,則應使用空行將其與標題分隔開。
訊息正文應該簡潔易懂,並包含完整的推理。除非需要理解變更,否則範例、程式碼片段和過於詳細的資訊應留待錯誤註解、網路審查或郵件清單中討論。
文字格式和拼寫應遵循與文件和程式碼內註解相同的規則,例如大小寫、句號等。
如果提交是在另一個最近提交的修補程式之上進行錯誤修復,或者是要還原或重新套用修補程式,請包含先前相關提交的 git 提交雜湊值。這可以像「還原提交 NNNN,因為它導致 PR#」一樣簡單。
如果修補程式已通過審查,請添加指向其審查頁面的連結,如這裡所示。如果修補程式修復了 GitHub 問題中的錯誤,我們鼓勵添加對已解決問題的引用,如這裡所述。
也可以在提交訊息中添加其他中繼資料,以自動化流程,包括供下游使用者使用。這些中繼資料可以包含指向並非整個社群都能使用的資源的連結。但是,此類連結和/或中繼資料不應取代提交訊息本身的說明性。請注意,提交的程式碼中不應包含此類非公開連結。
對於輕微違反這些建議的情況,社群通常傾向於提醒貢獻者注意此政策,而不是還原提交。輕微的修正和遺漏可以透過回覆提交郵件清單來處理。
修補程式還原政策¶
作為一個社群,我們非常重視將程式碼庫的頂端保持在良好的狀態,同時允許快速迭代開發。因此,與其他一些開源專案相比,我們更傾向於使用還原來保持程式碼庫的健康,而且我們的規範也有些不同。
如果有人還原了您的變更,您應該如何回應?
請記住,修補程式被還原是正常且健康的。修補程式被還原並不一定意味著您做錯了什麼。
我們鼓勵您明確感謝還原修補程式的人為您完成了這項任務。
如果您需要更多資訊來解決問題,請在原始提交執行緒中與還原修補程式的作者聯繫。
您應該在什麼時候還原自己的變更?
當您發現變更存在嚴重問題時,應將其還原。我們強烈建議「還原至穩定版本」,而不是「繼續修復」。我們鼓勵先還原,離線調查,然後重新應用修復後的更新檔 - 如果有必要,可能會在另一輪審查之後。
如果您以無法快速修復的方式破壞了建置機器人,請還原。
如果在提交線程中報告了顯示問題的測試案例,請還原並離線調查。
如果您收到大量的 提交後審查 意見回饋,請在重新提交之前先還原並解決這些意見回饋。(可能在另一輪審查之後。)
如果其他貢獻者要求您還原,請還原並離線討論請求的優缺點(除非這樣做會進一步破壞樹尖的穩定性)。
您應該在什麼時候還原其他人的變更?
一般來說,如果作者本身會根據這些準則還原變更,我們鼓勵其他貢獻者也這樣做,以示對作者的禮貌。這是我們的規範與其他規範不同的主要情況之一;我們通常將還原視為開發過程中正常的一部分。我們不期望貢獻者始終在線,並且確信有問題的更新檔將被還原,我們可以在下次有機會時再處理它。
對還原有什麼期望?
請您自行判斷。如果您不確定,請在提交線程上發起電子郵件,尋求協助。我們並不是要列舉每種情況,而是要提供一組準則。
您應該確保還原變更可以提高樹尖的穩定性。有時,還原一系列變更中的一個變更可能會使情況變得更糟,而不是更好。我們期望做出合理的判斷,以確保還原了正確的更新檔或一組更新檔。
還原提交的提交訊息應說明為何要還原更新檔。
通常的做法是在原始提交電子郵件中回覆並提及還原。這既可以通知原始作者他們的更新檔已被還原,也可以幫助其他關注 llvm-commits 的人追蹤上下文。
理想情況下,您應該準備好一個可公開重現的測試案例來分享。在可能的情況下,我們鼓勵在提交線程或 PR 中分享測試案例。我們鼓勵還原者盡可能簡化測試案例並減少依賴關係。即使在還原您自己的更新檔時也是如此;記錄原因對於可能正在關注的其他人至關重要。
在沒有至少承諾為更新檔作者提供除錯根本原因的方法的情況下進行還原,這被認為是不合理的。如果出於某種原因無法共享公開的重現器(例如,需要更新檔作者無法訪問的硬體、內部工作負載的編譯時間急劇回歸等),則預計還原者將積極與更新檔作者合作,對候選更新檔進行除錯和測試。
還原應該及時。兩個小時前提交的變更可以在沒有事先討論的情況下還原。兩年前提交的變更則不應該這樣做。確切的轉折點很難說,但它可能是在樹上停留了幾天。如果您不確定,我們鼓勵您回覆提交線程,給作者一點時間回應,如果作者似乎沒有積極回應,則繼續還原。
重新應用還原的更新檔時,應更新提交訊息以說明已解決的問題以及解決方法。
取得提交權限¶
我們授予提交過高品質修補程式記錄的貢獻者提交權限。如果您想要提交權限,請發送電子郵件至 Chris 並附上您的 GitHub 用戶名。這適用於具有 SVN 存取權限的舊貢獻者以及新貢獻者。如果獲得批准,GitHub 邀請函將發送到您的 GitHub 帳戶。如果您沒有收到 GitHub 的通知,請直接前往 邀請連結。接受邀請後,您將獲得提交權限。
在獲得提交權限之前,通常的做法是請求具有提交權限的人代表您提交。在這樣做時,請提供您希望在提交的「作者」屬性中使用的姓名和電子郵件地址。
為了進行外部追蹤,提交的變更會在提交落地後不久自動反映在提交郵件列表中(例如 llvm-commits)。請注意,這些郵件列表是經過審核的,大型提交需要審核者批准電子郵件的情況並不少見,因此如果提交沒有立即出現在存檔中,請不要擔心。
如果您最近獲得了提交權限,則以下政策適用
您被授予對 LLVM 所有部分的「提交後批准」權限。有關如何獲得修補程式批准的資訊,請參閱 LLVM 程式碼審查政策和實務。獲得批准後,您可以自行提交。
您可以提交您認為顯而易見的修補程式,而無需批准。這顯然是一個主觀的決定,我們只是希望您做出良好的判斷。例子包括:修復構建錯誤、還原明顯損壞的修補程式、文件/註釋變更以及任何其他次要變更。避免提交僅限格式或空格的變更,除非您打算對程式碼進行後續變更。此外,請盡量將格式或空格變更與功能變更分開,方法是在變更格式之前(理想情況下)或之後進行更正。此類變更應高度本地化,並且提交訊息應明確說明提交不打算變更功能,通常通過說明它是 NFC 來實現。
您可以提交您已貢獻或維護(即已被分配責任)的 LLVM 部分的修補程式,而無需批准,前提是此類提交不得破壞構建。這是一種「信任但驗證」的政策,此類提交會在提交後進行審查。
多次違反這些政策或單次嚴重違反可能會導致提交權限被撤銷。
無論如何,您的變更仍然需要經過 程式碼審查(在提交之前或之後,具體取決於變更的性質)。我們鼓勵您也審查其他人的修補程式,但您沒有義務這樣做。
進行重大變更¶
當開發人員開始一個旨在將其貢獻回 LLVM 的重大新專案時,他們應盡可能在 LLVM 論壇 上發布帖子,告知社群。這樣做的原因是
讓社群隨時了解 LLVM 的未來變化,
通過防止多方在不知情的情況下處理同一件事來避免重複工作,以及
確保在進行任何重大工作之前,討論並解決圍繞擬議工作的任何技術問題。
LLVM 的設計經過精心控管,以確保所有部分都能良好地整合在一起,並盡可能保持一致。如果您打算對 LLVM 的運作方式進行重大變更,或者想要新增重要的擴充功能,最好在開始動工之前先與開發社群取得共識。
新功能的設計定案後,工作本身應該以一系列漸進式變更的方式完成,而不是作為一個長期的開發分支。
漸進式開發¶
在 LLVM 專案中,我們將所有重大變更都以一系列漸進式修補程式的方式進行。我們非常不喜歡巨大的變更或長期的開發分支。長期開發分支有許多缺點:
分支必須定期合併主線。如果分支開發和主線開發發生在相同的程式碼片段中,解決合併衝突可能會花費大量時間。
社群中的其他人往往會忽略分支上的工作。
巨大的變更(在分支合併回主線時產生)極難進行程式碼審查。
我們的夜間測試基礎架構不會定期測試分支。
以單一大型變更形式開發的變更通常要等到整個變更集完成後才能運作。將其分解成一組較小的變更可以增加任何工作被提交到主儲存庫的機率。
為了克服這些問題,LLVM 採用漸進式開發風格,我們要求貢獻者在進行大型/侵入性變更時遵循這種做法。以下是一些技巧:
大型/侵入性變更通常需要進行許多次要變更,才能進行重大變更(例如 API 清理等)。這些類型的變更通常可以在進行重大變更之前完成,並且獨立於該工作。
如果可能的話,應將剩餘的相互關聯的工作分解成不相關的變更集。完成後,定義第一個增量,並就變更的最終目標達成共識。
集合中的每個變更都可以是獨立的(例如修復錯誤),也可以是朝著開發目標努力的一系列計劃變更的一部分。
每次變更都應盡可能保持小巧。這可以簡化您的工作(使其成為邏輯上的進展),簡化程式碼審查,並降低您收到變更負面回饋的可能性。小幅度的增量也有助於維護高品質的程式碼庫。
通常,進行重大變更之前的一個獨立步驟是新增新的 API,並慢慢地將客戶端遷移到使用新的 API。每個使用新 API 的變更通常都很「明顯」,可以在沒有審查的情況下提交。一旦新的 API 就位並開始使用,替換 API 的底層實作就會容易得多。這種實作變更在邏輯上與 API 變更是分開的。
如果您有興趣進行重大變更,但又感到害怕,請務必先討論變更/取得共識,然後詢問進行變更的最佳方法。
變更的歸屬¶
當貢獻者提交一個修補程式到 LLVM 專案時,其他具有提交權限的開發者可以在適當的情況下(根據程式碼審查的進度等)替作者提交該修補程式。在這樣做的時候,重要的是要保留貢獻者對其貢獻的正確歸屬。然而,我們不希望原始碼中充斥著隨機的歸屬,例如「這段程式碼由 J. Random Hacker 編寫」(這樣會造成干擾且分散注意力)。實際上,版本控制系統會完整記錄誰修改了什麼,而 CREDITS.txt 檔案則描述了更高級別的貢獻。如果您要提交其他人編寫的修補程式,請按照提交訊息章節中概述的簡單方式來註明變更。總之,請勿在原始碼中添加貢獻者的姓名。
此外,除非其他作者已將修補程式提交到專案,或者您已被授權代表他們提交修補程式(例如,你們一起工作,且您的公司授權您提交這些修補程式),否則請勿提交由他人編寫的修補程式。作者應先將修補程式提交到相關專案的提交列表、開發列表或 LLVM bug 追蹤器元件。如果有人私下傳送修補程式給您,請鼓勵他們先將其提交到適當的列表。
我們之前的版本控制系統(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 論壇 上討論設計和可維護性方面的意見回饋。
文件:C API 的任何變更都必須記錄在發行說明中,以便未關注專案的外部使用者清楚瞭解 C API 的變更和發展。
更新工具鏈需求¶
我們打算隨著時間的推移要求更新的工具鏈。這表示 LLVM 的程式碼庫可以使用標準化的更新版本 C++。要求使用更新的工具鏈來建置 LLVM 對於那些建置 LLVM 的人來說可能很痛苦;因此,它只會透過以下流程來完成
一般的目標是至少支援過去 3 年的 LLVM 和 GCC 版本。這個基於時間的準則並不嚴格:我們可能會支援更舊的編譯器,或者決定支援更少的版本。
向 LLVM 論壇 發送 RFC
詳細說明版本升級的好處(例如 LLVM 應該使用哪些更新的 C++ 語言或程式庫功能;避免特定編譯器版本的編譯錯誤等)。
詳細說明重要平台(例如 Ubuntu LTS 狀態)的缺點。
一旦 RFC 達成共識,請更新 CMake 工具鏈版本檢查以及 入門指南。這為編譯 LLVM 的開發人員提供了一個更平穩的過渡途徑,因為可以使用 CMake 旗標將錯誤轉換為警告。這是一個重要的步驟:LLVM 仍然沒有需要新工具鏈的程式碼,但很快就會有。如果你編譯 LLVM 但沒有閱讀論壇,我們應該告訴你!
確保至少有一個 LLVM 發佈版本出現過這種軟錯誤。並非所有開發人員都編譯 LLVM 的最新版本。這些受發佈版本限制的開發人員也應該被告知即將發生的變更。
在上述 LLVM 發佈版本分支後,將軟錯誤轉換為硬錯誤。
更新 程式碼標準 以允許我們在 RFC 中明確核准的新功能。
開始在 LLVM 的程式碼庫中使用新功能。
使用 CI 系統¶
LLVM 專案的主要持續整合 (CI) 工具是 LLVM Buildbot。它使用不同的「建置器」來涵蓋各種子專案和配置。建置在不同的「工作器」上執行。建置器和工作器由社群成員配置和提供。
Buildbot 會追蹤主分支和發佈分支上的提交。這表示在修補程式合併到這些分支(又稱為合併後測試)之後,就會建置和測試修補程式。這也表示偶爾中斷建置是可以的,因為期望貢獻者使用所有可能的配置來建置和測試他們的修補程式是不合理的。
如果您的提交中斷了建置
請盡快修復建置,因為這可能會阻礙其他貢獻者或下游使用者。
如果您需要更多時間來分析和修復錯誤,請還原您的變更以解除對其他人的阻礙。
如果其他人中斷了建置,並且這阻礙了您的工作
請在 GitHub(如果有的話)的程式碼審查中發表評論,或透過電子郵件通知作者,說明問題以及這對您的影響。新增指向損壞建置和錯誤訊息的連結,以便人們了解問題。
如果這阻礙了您的工作,請還原提交,請參閱 revert_policy。
如果建置/工作器永久損壞
第一步:聯絡工作器的擁有者。您可以在「工作器」標籤頁的建置頁面上找到工作器「管理員」的姓名和聯絡資訊
第二步:如果擁有者沒有回應或修復工作器,請升級至 BuildBot 維護者 Galina Kostanova。
第三步:如果 Galina 無法幫助您,請升級至 基礎設施工作組。
將新元件引入 LLVM¶
LLVM 社群是一個充滿活力和令人興奮的地方,我們希望包容新的專案並培育新的社群,並加強業界和學術界的合作。
也就是說,我們需要在包容新想法和人員與新程式碼所需的持續維護成本之間取得平衡。因此,根據所需的詳細程度和責任,我們對將主要的新元件引入 LLVM 世界有一般性的 支援政策。「核心」專案比「周邊」專案需要更高的審查程度,而後者可能還有其他差異。
然而,這實際上只是為了涵蓋我們已經看到出現的常見情況:不同的情況是不同的,我們也願意討論不尋常的情況 - 只需在 LLVM 論壇 上發起一個 RFC 討論串。
新增目標¶
LLVM 非常樂於接受新的目標,甚至是實驗性的目標,但在新增大量程式碼時可能會出現一些問題,而且後端通常是批量新增的。新的目標需要與編譯器的其他「核心」部分相同級別的支援,因此它們包含在我們的 支援政策 的「核心層」中。
我們發現,引入大量新的程式碼,然後嘗試在樹中修復出現的問題,由於各種原因是有問題的。由於這些原因,新的目標「總是」作為「實驗性」新增,直到它們被證明是穩定的,然後才移到非實驗性。
這兩個類別之間的差異為:
預設不會建置實驗性目標(需要在 CMake 時間明確啟用)。
僅在啟用實驗性目標時才會出現的測試失敗、錯誤和建置中斷,如果這些問題是由與目標無關的變更所導致,則應由目標背後的社群負責修復。
後端以**實驗性**模式向上游發佈的基本規則為:
每個目標都必須有一個程式碼擁有者。必須在第一次合併時更新CODE_OWNERS.TXT檔案。程式碼擁有者確保目標的變更經過審查,並引導整體工作。
目標背後必須有一個活躍的社群。該社群將通過提供建置機器人、修復錯誤、回答 LLVM 社群的問題以及確保新目標不會破壞任何其他目標或通用程式碼來幫助維護目標。預計在目標程式碼的整個生命週期中,這種行為都將持續下去。
程式碼必須沒有爭議性問題,例如,IR 的行為方式或前端應如何形成 IR 的重大變更,除非大多數社群通過重構(IR 標準)達成一致,並在合併新目標變更**之前**遵循IR 向後相容性。
程式碼符合本開發人員政策文件中規定的所有策略,包括授權、專利和編碼標準。
目標應該有關於其工作原理的合理文件(ISA、ABI 等),或公開可用的模擬器/硬體(免費或價格合理)——最好兩者兼具。這允許開發人員驗證假設、理解限制並審查可能影響目標的程式碼。
此外,後端升級為**正式版**的規則為:
目標必須滿足所有其他最低要求,並且在樹中穩定存在至少 3 個月。這個冷卻期是為了確保後端和目標社群在可預見的未來能夠承受持續的向上游開發。
目標的程式碼必須已完全適應本策略以及編碼標準。為進入實驗模式而做出的任何例外都必須在成為正式版**之前**修復。
測試覆蓋率需要廣泛且編寫良好(小型測試、文件齊全)。建置目標
check-all
必須在新目標建置的情況下通過,並且在適用的情況下,test-suite
也必須至少在一個配置中無錯誤通過(例如,通過建置機器人公開演示)。需要創建並積極維護公共建置機器人,除非目標不需要額外的建置機器人(例如,
check-all
涵蓋所有測試)。新目標的 CI 基礎設施越相關且公開,LLVM 社群就越容易接受它。
要**繼續**作為受支援的正式目標:
維護者必須在目標的整個生命週期中繼續遵循這些規則。持續違反上述規則和策略可能導致從程式碼庫中完全移除目標。
支援、文件或測試覆蓋率方面的降低將使目標成為其他目標的障礙,並被視為棄用候選,最終被移除。
簡而言之,這些規則對於目標獲取和保留其狀態是必要的,也是定義位元腐壞的標記,並將用於從未維護的目標中清理樹。
希望將新目標添加到 LLVM 的人必須遵循以下過程
閱讀本節並確保您的目標符合所有要求。對於次要問題,您的社群將負責在初始合併後立即進行所有必要的調整。
向 LLVM 論壇 發送評論請求 (RFC),描述您的目標以及它如何滿足所有要求,以及已經完成和需要完成哪些工作以滿足官方目標要求。確保公開任何和所有有爭議的問題、基本代碼中需要的更改、表單生成器等。
一旦獲得正面回應,LLVM 社群就可以開始審查實際的補丁(但它們可以事先準備好,以支持 RFC)。創建一系列 N 個補丁,編號為「1/N」到「N/N」(確保 N 是一個實際數字,而不是字母「N」),以完成目標的基本結構。
初始補丁應在 clang 和 LLVM 中添加文檔、代碼所有者和三元組支持。以下補丁添加了 TableGen 基礎結構來描述目標並將指令降低到組件。最後一個補丁必須通過廣泛的 LIT 測試(IR 到 MIR、MIR 到 ASM 等)表明目標可以正確降低。
某些補丁可能會在其他補丁之前獲得批准,但只有在 *所有* 補丁都獲得批准後,才能一次性合併整個集合。這是為了確保所有更改作為單個塊都是好的。
在初始合併之後,目標社群可以停止對補丁進行編號,並開始異步處理目標以完成支持。他們仍然應該尋求在初始階段幫助過他們的人的審查,以確保進展仍然一致。
一旦滿足所有官方要求(如上所述),代碼所有者應通過向 LLVM 論壇 發送另一個 RFC 來請求默認啟用目標。
將已建立的專案添加到 LLVM 單一儲存庫¶
LLVM 單一儲存庫 是 LLVM 世界中開發的中心點,擁有所有主要的 LLVM 組件,包括 LLVM 優化器和代碼生成器、Clang、LLDB 等。 單一儲存庫 通常很棒,因為它們允許對專案進行原子提交、簡化 CI 並使子社群更容易協作。
與新目標一樣,單一儲存庫中已存在的大多數專案都被認為屬於我們 支援政策 的 *核心層*。將內容添加到 LLVM 單一儲存庫的負擔必須非常高 - 社群中的每個人都會檢查添加到此儲存庫的代碼。因此,我們對組件設定了與「官方目標」類似的高標準,它們
必須與 LLVM 專案推進編譯器、語言、工具、運行時等的使命總體一致。
必須符合本開發人員政策文件中規定的所有政策,包括許可證、專利、編碼標準和行為準則。
必須有一個活躍的社群來維護代碼,包括已建立的代碼所有者。
應該有關於它是如何工作的合理文檔,包括高質量的 README 文件。
應該有 CI 來捕捉專案本身內部或由於底層 LLVM 依賴項導致的破壞。
應該讓代碼沒有社群認為有爭議的問題,或者正在明確解決這些問題的道路上。
必須透過 LLVM RFC 程序提出,並經 LLVM 社群核准才能加入 — 最終將由上述的「應該」條件來決定。
如果您有一個認為加入 LLVM 單一儲存庫很適合的專案,請在 LLVM Discourse 論壇 上開啟一個 RFC 主題,開始進行討論。這個過程可能需要一些時間和反覆修改 — 請不要因此而灰心或卻步!
如果您有一個處於早期階段的專案,您認為與 LLVM 的目標一致,請參閱「新專案孵化」章節。
新專案孵化¶
將新專案加入 LLVM 單一儲存庫的門檻故意設定得很高,但這可能會對新穎的專案產生寒蟬效應。為了幫助培養這類專案,LLVM 支援一種「孵化器」流程,這個流程更容易上手。它為潛力十足的新頂級專案和子專案提供空間,讓它們在擁有足夠的程式碼來證明其效用和發展社群之前,能夠達到一定的規模。這也允許已經獲得許可為 LLVM 旗下專案做出貢獻的團隊之間進行協作。
符合以下條件的專案可以考慮加入 LLVM 孵化器:
必須與 LLVM 專案推進編譯器、語言、工具、運行時等的使命總體一致。
必須符合本開發者政策文件中規定的許可證、專利和行為準則政策。
必須有文件化的章程和開發計畫,例如 README 檔案、使命宣言和/或宣言。
應符合程式碼標準、漸進式開發流程和其他期望。
應對其希望最終培養的社群有概念,並且應有來自不同組織/機構的成員感興趣。
應該有可行的途徑最終成為 LLVM 單一儲存庫 中專屬的頂級專案或子專案。
應包含一則聲明(例如在專案 README 或網頁中),說明該專案處於「孵化狀態」,未包含在 LLVM 發行版本中(請參閱以下建議措辭)。
必須透過 LLVM RFC 程序提出,並經 LLVM 社群核准才能加入 — 最終將由上述的「應該」條件來決定。
也就是說,該專案不需要有任何程式碼即可開始,也不需要有任何既有的社群!此外,孵化中的專案可能會經歷違反上述「應該」準則的過渡狀態,或者會讓它們不適合直接納入單一儲存庫(例如,尚未適當分解的依賴項、利用尚未進入上游的實驗性元件或 API 等)。
- 經核准後,llvm-admin 群組可以授予新專案:
LLVM Github 組織中的一個新儲存庫 — 但不是 LLVM 單一儲存庫。
與其他 LLVM 論壇一起託管的新郵件清單、論壇和/或 Discord 聊天。
其他基礎架構整合可以根據具體情況討論。
升級到單一儲存庫將遵循現有的流程和標準,成為單一儲存庫中的一級專案。同樣地,孵化中的專案最終可能會被淘汰,但目前尚未建立相關流程。如果遇到這種情況,請在 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.
版權、許可證和專利¶
備註
本節涉及法律事項,但未提供法律建議。我們不是律師,請向合格的律師尋求法律諮詢。
本節說明 LLVM 專案的版權、授權和專利問題。程式碼的版權歸程式碼貢獻者所有。程式碼以寬鬆的開放原始碼授權條款授權,即 Apache-2.0 附 LLVM 例外條款的授權,其中包含版權和專利授權。當您將程式碼貢獻給 LLVM 專案時,即表示您同意根據這些條款授權。
在某些情況下,可以將以其他授權授權的程式碼新增至程式碼庫。但是,這只有在獲得 LLVM 基金會董事會批准的情況下才能進行,並且貢獻者應計畫至少需要 4-6 週的批准時間。如果您想根據其他授權貢獻程式碼,請建立一個包含您要貢獻的程式碼的拉取請求,並發送電子郵件至board@llvm.org 請求審查。
如果您對這些主題有任何疑問或意見,請在LLVM 論壇上詢問。但是,請注意,大多數編譯器開發人員都不是律師,因此您不會獲得正式的法律建議。
版權¶
LLVM 專案不會收集版權轉讓,這表示專案中程式碼的版權歸各自的貢獻者所有。因為您(或您的公司)保留您貢獻的程式碼的所有權,所以您知道它只能根據您貢獻時採用的開放原始碼授權條款使用:未經您的同意,您貢獻的授權條款在未來不得更改。
因為 LLVM 專案不要求版權轉讓,所以更改 LLVM 授權需要追蹤 LLVM 的貢獻者,並讓他們同意更改授權對其貢獻是可以接受的。我們認為,重新授權的高門檻對專案有利,因為貢獻者不必擔心他們的程式碼會以他們不同意的方式使用。
重新授權¶
儘管有上一段的說明,LLVM 專案目前正在進行一項大規模的授權變更工作,旨在解決幾個問題
舊的授權使得將程式碼從(例如)編譯器移至執行時程式庫變得困難,因為執行時程式庫使用與編譯器其餘部分不同的授權。
有些貢獻未提交給 LLVM,因為擔心專案要求的專利授權過於廣泛。
專利授權是 LLVM 專案獨有的,不是由律師撰寫的,而且很難確定提供了哪些保護(如果有)。
重新授權的範圍是所有被視為 LLVM 專案一部分的程式碼,包括主要的 LLVM 儲存庫、執行時程式庫 (compiler_rt、OpenMP 等)、Polly 和所有其他子專案。有一些例外情況
從其他專案匯入的程式碼(例如 Google Test、Autoconf 等)將保持原樣。這些程式碼不是作為 LLVM 專案的一部分開發的,而是由 LLVM 使用的。
有些子專案不切實際或不值得重新授權(例如 llvm-gcc 和 dragonegg)。這些專案將從 LLVM 專案中分離出來(例如,分離到單獨的 GitHub 專案中),允許有興趣的人在其他地方繼續開發。
為了重新授權 LLVM,我們將徵求儲存庫中程式碼的所有版權持有者的同意,或者如果我們無法獲得同意,我們可能會移除/重寫程式碼。這是一項龐大而具有挑戰性的專案,需要相當長的時間才能完成。
自 2024 年 6 月 1 日(2024 年 6 月第一日)起,新的貢獻只需涵蓋新的 LLVM 授權,即 Apache-2.0 WITH LLVM-exception。在此日期之前,專案要求所有貢獻都必須在新的授權和舊的授權下進行。
如果您是在 2019 年 1 月 19 日之前對 LLVM 做出貢獻的貢獻者,並且尚未按照說明進行操作,請按照 https://foundation.llvm.org/docs/relicensing/ 中「個別重新授權協議」一節中的說明,在新的授權下重新授權您的貢獻。
新的 LLVM 專案授權架構¶
LLVM 的貢獻根據 Apache 授權,版本 2.0 授權,並有兩個有限的例外情況,旨在確保 LLVM 擁有非常寬鬆的授權。總體而言,此授權的名稱為「具有 LLVM 例外的 Apache 2.0 授權」。這些例外情況如下:
---- LLVM Exceptions to the Apache 2.0 License ----
As an exception, if, as a result of your compiling your source code, portions
of this Software are embedded into an Object form of such source code, you
may redistribute such embedded portions in such Object form without complying
with the conditions of Sections 4(a), 4(b) and 4(d) of the License.
In addition, if you combine or link compiled forms of this Software with
software that is licensed under the GPLv2 ("Combined Software") and if a
court of competent jurisdiction determines that the patent provision (Section
3), the indemnity provision (Section 9) or other Section of the License
conflicts with the conditions of the GPLv2, you may retroactively and
prospectively choose to deem waived or otherwise exclude such Section(s) of
the License, but only in their entirety and only with respect to the Combined
Software.
我們打算讓 LLVM 永久開源並在寬鬆的授權下提供 - 這促進了 LLVM 的最廣泛採用,方法是**允許從 LLVM 派生商業產品**,限制很少,並且不要求將任何衍生作品也開源。特別是,LLVM 的授權不是像 GPL 那樣的「著作傳播」授權。
「具有 LLVM 例外的 Apache 2.0 授權」允許您
自由下載和使用 LLVM(全部或部分)用於個人、內部或商業目的。
將 LLVM 包含在您建立的軟體包或發行版中。
將 LLVM 與其他所有主要開放原始碼授權(包括 BSD、MIT、GPLv2、GPLv3…)下授權的程式碼結合使用。
對 LLVM 程式碼進行更改,而無需將其貢獻回專案 - 儘管我們非常感謝您的貢獻!
但是,它對您施加了以下限制
如果您重新發布 LLVM,則必須保留著作權聲明:您不能刪除著作權標頭或將其替換為您自己的標頭。
包含 LLVM 的二進制文件必須複製著作權聲明(例如,在包含的 README 文件或「關於」框中),除非 LLVM 程式碼是作為編譯的副產品添加的。例如,如果像 compiler_rt 或 libc++ 這樣的 LLVM 執行時庫是由編譯器自動包含在您的應用程式中的,則您不需要對其進行說明。
您不能使用我們的名稱來宣傳您的產品(無論是否源自 LLVM)- 儘管您可以就您對 LLVM 程式碼的使用做出真實陳述,而不會暗示我們有贊助。
LLVM 没有任何担保。
我們希望 LLVM 程式碼得到廣泛使用,並相信這提供了一個對專案貢獻者和使用者都非常有利的模型。有關 Apache 2.0 授權的更多資訊,請參閱由 Apache 專案維護的 Apache 授權常見問題解答。
專利¶
Apache 2.0 授權的第 3 節是一項專利授權,根據該授權,專案程式碼的貢獻者貢獻使用其任何專利的權利,否則這些專利將因該程式碼貢獻而受到侵犯(保護該程式碼的使用)。此外,對於任何就 LLVM 中的程式碼提起專利訴訟的人,都將撤銷其專利授權 - 這透過為程式碼庫提供「專利公地」並總體上降低專利訴訟的可能性來保護社群。
此授權明確規定了程式碼貢獻中包含的專利範圍。為了幫助解釋這一點,Apache 授權常見問題 使用了一些問答來解釋這個範圍,為了方便起見,我們在此複製這些問答(作為參考,「ASF」是 Apache 軟體基金會,但指南仍然有效)
Q1: If I own a patent and contribute to a Work, and, at the time my
contribution is included in that Work, none of my patent's claims are subject
to Apache's Grant of Patent License, is there a way any of those claims would
later become subject to the Grant of Patent License solely due to subsequent
contributions by other parties who are not licensees of that patent.
A1: No.
Q2: If at any time after my contribution, I am able to license other patent
claims that would have been subject to Apache's Grant of Patent License if
they were licensable by me at the time of my contribution, do those other
claims become subject to the Grant of Patent License?
A2: Yes.
Q3: If I own or control a licensable patent and contribute code to a specific
Apache product, which of my patent claims are subject to Apache's Grant of
Patent License?
A3: The only patent claims that are licensed to the ASF are those you own or
have the right to license that read on your contribution or on the
combination of your contribution with the specific Apache product to which
you contributed as it existed at the time of your contribution. No additional
patent claims become licensed as a result of subsequent combinations of your
contribution with any other software. Note, however, that licensable patent
claims include those that you acquire in the future, as long as they read on
your original contribution as made at the original time. Once a patent claim
is subject to Apache's Grant of Patent License, it is licensed under the
terms of that Grant to the ASF and to recipients of any software distributed
by the ASF for any Apache software product whatsoever.
舊版授權結構¶
備註
程式碼庫先前是根據此處描述的條款授權。我們正在將其重新授權為新的方法(如上所述)。超過 99% 對 LLVM 的貢獻都涵蓋在 Apache-2.0 WITH LLVM 例外授權之下。一小部分 LLVM 程式碼仍然僅受舊版授權的保護。2024 年 6 月 1 日之後的貢獻僅受新授權的保護。
我們打算讓 LLVM 永久開源,並使用寬鬆的開源授權。LLVM 中的程式碼在 伊利諾大學/NCSA 開源授權 下可用,其概要如下
您可以自由發布 LLVM。
如果您重新發布 LLVM,則必須保留版權聲明。
從 LLVM 派生的二進制文件必須複製版權聲明(例如,在包含的 README 檔案中)。
您不能使用我們的名稱來宣傳您的 LLVM 派生產品。
LLVM 没有任何担保。
我們相信這將促進 LLVM 的最廣泛採用,因為它**允許從 LLVM 派生商業產品**,限制很少,並且不要求將任何派生作品也開源(即 LLVM 的授權不是像 GPL 那樣的「著作傳播」授權)。如果您需要進一步說明,建議您閱讀 授權。
除了 UIUC 授權之外,LLVM 的執行時程式庫組件(**compiler_rt、libc++ 和 libclc**)也在 MIT 授權 下授權,該授權不包含二進制文件重新發布條款。作為這些執行時程式庫的使用者,這意味著您可以選擇在任何一種授權下使用程式碼(因此不需要二進制文件重新發布條款),並且作為對程式碼的貢獻者,您同意對這些程式庫的任何貢獻都在這兩種授權下授權。我們認為這對於執行時程式庫很重要,因為它們被隱式連結到應用程式中,因此不應使這些應用程式受二進制文件重新發布條款的約束。這也意味著可以將程式碼從(例如)libc++ 移動到 LLVM 核心而無需擔心,但未經版權所有者的許可,不能將程式碼從 LLVM 核心移動到 libc++。