在昇騰設(shè)備上做分布式訓(xùn)練時(shí)HCCLHuawei Collective Communication Library就是那個(gè)藏在底層、負(fù)責(zé)多卡和跨節(jié)點(diǎn)梯度同步的集合通信庫(kù)。很多做模型訓(xùn)練的同學(xué)用過它但真正參與過它開發(fā)的并不多。這篇東西我想從一個(gè)貢獻(xiàn)者的視角把從提 Issue 到 PR 合入的完整鏈路拆開講一遍包括什么樣的 Issue 會(huì)被維護(hù)者認(rèn)真看、PR 怎么寫才不用來(lái)回折騰十輪、CI 掛了先查哪里、以及 code review 時(shí)那些不好意思問出口的潛規(guī)則。如果你已經(jīng)有 C/C 或 Python 基礎(chǔ)想找一個(gè)有真實(shí)落地場(chǎng)景的開源項(xiàng)目練手HCCL 其實(shí)是個(gè)比想象中更友好的選擇。這篇文章會(huì)從項(xiàng)目背景、Issue 規(guī)范、環(huán)境準(zhǔn)備、PR 流程、CI 調(diào)試到合入后的收尾工作逐步帶你把整套流程走通。哪怕你還沒碰過集合通信只要愿意讀代碼、愿意跑測(cè)試也能找到自己可以下手的位置。1. 項(xiàng)目畫像先搞清楚 HCCL 到底是什么1.1 它在分布式訓(xùn)練棧里的位置在聊怎么給 HCCL 貢獻(xiàn)代碼之前先花點(diǎn)時(shí)間把項(xiàng)目本身講清楚。HCCL 是昇騰 AI 加速卡上的集合通信庫(kù)對(duì)標(biāo)的是 GPU 生態(tài)里的 NCCL。訓(xùn)練大模型時(shí)數(shù)據(jù)并行是最常見的并行策略每張卡算完自己那一份梯度之后需要把梯度同步到所有卡上這個(gè)同步動(dòng)作就是靠集合通信庫(kù)來(lái)完成的。AllReduce、AllGather、ReduceScatter 這些通信原語(yǔ)就是 HCCL 對(duì)外提供的核心能力。你可以把它理解成快遞系統(tǒng)里的分揀中心每張卡都往里面投遞自己的梯度包裹分揀中心負(fù)責(zé)按照規(guī)則重新打包再派送給所有卡。如果分揀中心效率低整個(gè)訓(xùn)練任務(wù)都會(huì)卡在等待上。這也是為什么集合通信庫(kù)的性能優(yōu)化如此重要——哪怕只提升 10% 的通信效率在大規(guī)模訓(xùn)練里節(jié)省的時(shí)間成本都是非?？捎^的。對(duì)貢獻(xiàn)者來(lái)說這個(gè)位置意味著兩件事一是你寫的代碼會(huì)被真實(shí)的高性能計(jì)算場(chǎng)景使用改動(dòng)的影響面很直觀二是它涉及的知識(shí)面比較寬包括操作系統(tǒng)、網(wǎng)絡(luò)協(xié)議、硬件拓?fù)?、并發(fā)編程但每個(gè)方向都不是說你要成為專家才能參與很多任務(wù)其實(shí)是在已有代碼框架上做增量?jī)?yōu)化和修補(bǔ)。1.2 代碼倉(cāng)庫(kù)和模塊劃分HCCL 的源碼可以通過公開代碼托管平臺(tái)獲取常見的路徑是在 Gitee 或 GitHub 上搜索相關(guān)組織下的 HCCL 倉(cāng)庫(kù)。拿到源碼之后你會(huì)發(fā)現(xiàn)它并不是一個(gè)特別龐大的項(xiàng)目但目錄結(jié)構(gòu)劃分得很清晰。核心內(nèi)容一般集中在通信算子的實(shí)現(xiàn)、設(shè)備管理、拓?fù)浒l(fā)現(xiàn)、傳輸鏈路這幾個(gè)模塊里。從新人的角度我建議先不要把精力放在底層傳輸鏈路上那個(gè)模塊涉及到對(duì)硬件驅(qū)動(dòng)的理解排查問題的門檻很高。相對(duì)友好的切入點(diǎn)是集合通信算子的上層邏輯、工具腳本、文檔注釋和測(cè)試用例。比如你看到某個(gè)算子在特定數(shù)據(jù)大小下性能異常順著調(diào)用鏈往下查可能定位到的是內(nèi)存分配策略或者同步等待邏輯的問題這種問題的修復(fù)往往只涉及幾百行代碼但對(duì)于理解整個(gè)項(xiàng)目幫助極大。順便說一句HCCL 的代碼風(fēng)格整體比較規(guī)整大量使用 C 特性但也保留了不少 C 風(fēng)格的接口設(shè)計(jì)。原因很簡(jiǎn)單這個(gè)庫(kù)需要被上層框架比如 PyTorch 的適配層通過 C 接口調(diào)用所以對(duì)外 API 用 C 接口更穩(wěn)定內(nèi)部的實(shí)現(xiàn)則用 C 來(lái)保證開發(fā)效率。1.3 貢獻(xiàn)前的能力準(zhǔn)備先潑一盆冷水給 HCCL 貢獻(xiàn)代碼不是會(huì)寫 Python 調(diào)幾個(gè)框架就行的事情。它需要一定的 C/C 功底至少要能讀懂指針、引用、模板這些基礎(chǔ)概念理解多線程和鎖的用法以及具備通過日志和調(diào)試工具排查問題的經(jīng)驗(yàn)。但也不用被嚇住因?yàn)轫?xiàng)目里不只是代碼一種貢獻(xiàn)形式。文檔修正、示例代碼、測(cè)試補(bǔ)充、Issue 復(fù)現(xiàn)驗(yàn)證這些都是非常有價(jià)值的貢獻(xiàn)方式。尤其對(duì)于第一次參與開源的人來(lái)說從文檔和測(cè)試入手熟悉了整個(gè)流程之后再碰核心代碼是曲線比較平滑的一條路。環(huán)境方面如果你手頭有昇騰設(shè)備那當(dāng)然是最好的可以本地復(fù)現(xiàn)并驗(yàn)證性能改動(dòng)。如果沒有也可以貢獻(xiàn)一些不依賴硬件的代碼邏輯優(yōu)化或者在 CI 環(huán)境里去跑測(cè)試。只不過需要提前說明的是HCCL 的很多測(cè)試是依賴真實(shí)硬件環(huán)境的純軟件模擬環(huán)境只能覆蓋一部分功能這個(gè)限制對(duì)所有貢獻(xiàn)者都一樣不是你一個(gè)人的問題。2. 從一條合格 Issue 開始2.1 Issue 不是吐槽區(qū)我見過很多新手在 GitHub/Gitee 上提 Issue開頭就是“訓(xùn)練報(bào)錯(cuò)了求大佬看看”然后附一張模糊的截圖沒有版本號(hào)沒有日志沒有復(fù)現(xiàn)步驟。這種 Issue 基本不可能得到有效的回復(fù)——不是維護(hù)者不熱情而是信息不足以定位問題。高質(zhì)量開源協(xié)作的第一步是學(xué)會(huì)提一條合格的 Issue。一個(gè)合格的 HCCL Issue必須包含幾個(gè)核心要素問題現(xiàn)象、復(fù)現(xiàn)步驟、環(huán)境信息、日志信息?，F(xiàn)象描述要準(zhǔn)確比如“在 8 卡環(huán)境執(zhí)行 AllReduce 時(shí)當(dāng)數(shù)據(jù)量為 512MB 時(shí)性能比預(yù)期低 30%”就比“訓(xùn)練很慢”有用得多。復(fù)現(xiàn)步驟要可操作別人按你的步驟能走通。環(huán)境信息包括操作系統(tǒng)版本、CANN 版本、HCCL 版本、固件驅(qū)動(dòng)版本、卡型號(hào)和拓?fù)洹Ｈ罩拘畔t是運(yùn)行時(shí)的報(bào)錯(cuò)輸出、HCCL 日志通常由環(huán)境變量控制開關(guān)以及必要的堆棧信息。有人可能會(huì)覺得我提個(gè) Issue 而已還需要整理這么多東西嗎換個(gè)角度想如果你是那個(gè)需要花半小時(shí)甚至更久去復(fù)現(xiàn)問題的維護(hù)者你希望看到什么樣的報(bào)告將心比心把信息整理清楚本身就是對(duì)維護(hù)者勞動(dòng)的尊重。2.2 一份能加速處理的 Issue 長(zhǎng)什么樣我以一個(gè)真實(shí)的 bug 類 Issue 為例給你拆解一下模板要素標(biāo)題[Bug] AllReduce 在數(shù)據(jù)量為 256MB 時(shí)觸發(fā)段錯(cuò)誤 環(huán)境信息 - 操作系統(tǒng)Ubuntu 20.04.6 LTS - CANN 版本8.0.RC1 - HCCL 版本v1.8.1 - 固件驅(qū)動(dòng)24.1.rc1 - 硬件4 張 Atlas 訓(xùn)練卡單機(jī)單卡環(huán)形互聯(lián) 復(fù)現(xiàn)步驟 1. 編譯 examples/allreduce_benchmark參數(shù)配置如下省略具體參數(shù) 2. 設(shè)置 HCCL_LOGFILE/tmp/hccl.log 環(huán)境變量 3. 啟動(dòng)測(cè)試程序數(shù)據(jù)量設(shè)置為 256MB 4. 觀察程序退出碼 期望行為正常完成集合通信并輸出正確結(jié)果。 實(shí)際行為程序在通信初始化階段崩潰退出碼 -11堆棧顯示在拓?fù)浒l(fā)現(xiàn)模塊具體報(bào)錯(cuò)粘貼。 日志片段 粘貼關(guān)鍵日志避免貼整個(gè)文件這個(gè)模板的信息密度很高維護(hù)者拿到手可以直接開始復(fù)現(xiàn)。值得注意的一點(diǎn)是“數(shù)據(jù)量為 256MB 時(shí)崩潰128MB 或 512MB 時(shí)正?！边@種信息非常關(guān)鍵因?yàn)樗軒椭S護(hù)者快速縮小問題范圍——可能涉及內(nèi)存池分配策略、通信緩沖區(qū)的邊界條件或者某個(gè)特定數(shù)據(jù)分片邏輯。另外如果問題涉及性能最好附上基線數(shù)據(jù)和實(shí)測(cè)數(shù)據(jù)的對(duì)比說明是在什么條件測(cè)的。性能問題比崩潰問題更難處理因?yàn)樗赡芎途W(wǎng)絡(luò)拓?fù)?、CPU 頻率、PCIe/NVLink/HCCS 鏈路狀態(tài)都有關(guān)沒有數(shù)據(jù)的性能 Issue 基本等于大海撈針。2.3 Issue 里的溝通禮儀Issue 提完之后你可能會(huì)遇到幾種情況。一種是維護(hù)者很快回復(fù)“能否提供更多信息”這時(shí)你需要及時(shí)補(bǔ)充一種是長(zhǎng)時(shí)間沒人回復(fù)這并不一定代表你的問題不重要可能是維護(hù)者比較忙也可能是你的 Issue 確實(shí)缺少必要信息還有一種情況是有人回復(fù)了但是給了一個(gè)和你預(yù)期不一樣的解釋方向。在 Issue 評(píng)論區(qū)溝通要保持專業(yè)和耐心。不要用“這東西怎么這么難用”這種抱怨語(yǔ)氣直接陳述技術(shù)問題就好。如果某個(gè)對(duì)話已經(jīng)偏離主題可以禮貌地提醒對(duì)方回到問題本身。如果維護(hù)者要求你驗(yàn)證某個(gè)修復(fù)補(bǔ)丁盡量第一時(shí)間去跑然后把結(jié)果反饋到評(píng)論區(qū)——這是建立信任的過程。這里還有一個(gè)很容易踩的坑在 Issue 里貼完整的大文件日志。幾萬(wàn)行的日志會(huì)把真正有用的錯(cuò)誤信息淹沒掉正確做法是先用 grep 過濾掉無(wú)關(guān)內(nèi)容只保留報(bào)錯(cuò)前后的關(guān)鍵幾十行并在日志片段外簡(jiǎn)要標(biāo)注每部分可能表示的含義。維護(hù)者每天要處理大量 Issue信息越聚焦你的問題被解決的優(yōu)先級(jí)就越高。3. 從 Issue 到開發(fā)計(jì)劃3.1 怎么篩選適合自己的任務(wù)不是所有 Issue 都需要你寫代碼。HCCL 的項(xiàng)目維護(hù)者通常會(huì)給 Issue 打標(biāo)簽比如 good first issue、help wanted、bug、enhancement 等。如果你是第一次參與建議優(yōu)先找 good first issue 或者文檔增強(qiáng)類的任務(wù)這類任務(wù)的技術(shù)依賴少評(píng)審要求相對(duì)寬松能幫你把整個(gè)工具鏈跑通。篩選任務(wù)的時(shí)候有幾點(diǎn)經(jīng)驗(yàn)可以分享。首先看 Issue 的創(chuàng)建時(shí)間——太老的問題可能已經(jīng)沒人關(guān)注你做了也可能不被接受。其次是看評(píng)論區(qū)的活躍度如果維護(hù)者在此前已經(jīng)給過一些方向性建議說明這個(gè)問題是被認(rèn)可的你可以在此基礎(chǔ)上展開。第三是評(píng)估影響范圍盡量選那些改動(dòng)文件不超過 10 個(gè)、核心邏輯相對(duì)獨(dú)立的問題。以 HCCL 為例一個(gè)對(duì)新人比較友好的任務(wù)是“補(bǔ)充某個(gè)通信原語(yǔ)在異常輸入下的錯(cuò)誤碼檢查”這種改動(dòng)通常只需要在 API 入口增加參數(shù)校驗(yàn)邏輯清晰、影響面可控。相比之下“優(yōu)化某拓?fù)湎?AllReduce 的帶寬利用率”這種任務(wù)雖然很有吸引力但往往需要你深入理解硬件拓?fù)浜途W(wǎng)絡(luò)通信機(jī)制調(diào)試周期很長(zhǎng)不建議拿來(lái)做第一個(gè) PR。3.2 認(rèn)領(lǐng)任務(wù)與溝通方式找到合適的 Issue 之后不要直接悶頭開始寫代碼。正確的做法是先在這個(gè) Issue 下面評(píng)論說明你想認(rèn)領(lǐng)這個(gè)任務(wù)并簡(jiǎn)單描述你打算怎么解決。好處有三個(gè)一是避免和其他貢獻(xiàn)者撞車讓別人知道這個(gè)任務(wù)有人在做二是維護(hù)者會(huì)給你反饋如果方案有問題可以及時(shí)調(diào)整避免白干三是有溝通記錄作為依據(jù)后續(xù)你提交 PR 時(shí)維護(hù)者更容易建立上下文。在評(píng)論認(rèn)領(lǐng)任務(wù)時(shí)可以簡(jiǎn)單描述你的技術(shù)背景和計(jì)劃時(shí)間線比如“我熟悉 C 和內(nèi)存管理計(jì)劃兩周內(nèi)完成修復(fù)并提交 PR”。這種信息能打消維護(hù)者對(duì)新人執(zhí)行力的顧慮。但要注意一旦你承諾了時(shí)間線最好能真的推進(jìn)如果有意外延期也應(yīng)該及時(shí)在 Issue 里同步而不是一直沉默。另外一個(gè)小技巧認(rèn)領(lǐng)任務(wù)后可以先把相關(guān)代碼讀一遍在評(píng)論里提出你的初判。比如“經(jīng)排查問題出現(xiàn)在 topology.c 中的設(shè)備發(fā)現(xiàn)邏輯可能和 PCIe 鏈路寬度檢測(cè)有關(guān)”。即使這個(gè)判斷不完全正確維護(hù)者也會(huì)覺得你是真的在做事而不是隨便占個(gè)坑。3.3 本地開發(fā)環(huán)境搭建開發(fā)環(huán)境搭建是很多新手真正卡住的地方。我的建議是分兩步走先搞定能在本地完成的工作讀代碼、編譯、跑靜態(tài)檢查再解決需要硬件資源的工作跑真實(shí)通信測(cè)試。HCCL 的代碼構(gòu)建一般依賴 Linux 環(huán)境、GCC 編譯器、CMake 和 Python 工具鏈。拿到源碼后按 README 的說明安裝好依賴依次執(zhí)行配置、編譯、安裝這幾個(gè)步驟即可。在配置階段有幾個(gè)選項(xiàng)比較重要比如是否啟用測(cè)試代碼、日志等級(jí)、調(diào)試符號(hào)等。如果你是做功能開發(fā)而非性能調(diào)優(yōu)建議打開調(diào)試符號(hào)和更詳細(xì)的日志輸出方便定位問題。沒有昇騰硬件的情況下依然可以完成編譯驗(yàn)證但鏈接階段可能會(huì)缺少某些底層庫(kù)。這種情況下一個(gè)可行的替代方案是只編譯與你改動(dòng)相關(guān)的模塊做語(yǔ)法級(jí)別的驗(yàn)證然后把完整的驗(yàn)證寄托在 CI 上。這個(gè)過程雖然不那么順暢但很多開源項(xiàng)目的貢獻(xiàn)者都是這樣工作的——本地環(huán)境不完全匹配CI 反而成了最終裁判。綁定硬件環(huán)境的測(cè)試跑不了還有一個(gè)折中方案編寫針對(duì)純軟件邏輯的單元測(cè)試。比如某個(gè)函數(shù)負(fù)責(zé)解析環(huán)境變量、計(jì)算通信緩沖區(qū)大小或者維護(hù)內(nèi)部狀態(tài)這種邏輯完全可以在宿主機(jī)上寫單元測(cè)試跑起來(lái)。HCCL 中這一類可以脫離硬件驗(yàn)證的代碼比你想象的多得多這也是很多新人能夠遠(yuǎn)程貢獻(xiàn)的主要原因。4. 寫 PR不只是把代碼推上去4.1 分支與提交規(guī)范代碼開發(fā)完成后提交 PR 的第一步是在遠(yuǎn)端倉(cāng)庫(kù)創(chuàng)建自己的分支。分支命名建議遵循一定的規(guī)范比如用 fix/ 開頭表示 bug 修復(fù)用 feature/ 表示新功能用 docs/ 表示文檔變更。這樣維護(hù)者從分支名就能快速判斷改動(dòng)的性質(zhì)。分支創(chuàng)建好之后開發(fā)過程中的 commit 信息也要講究。我見過很多 PR 里一個(gè) commit 寫了 800 行改動(dòng)信息只是“fix bug”這種提交歷史基本沒有可讀性。更好的做法是遵循 Conventional Commits 規(guī)范在提交信息里用簡(jiǎn)短的類型前綴說明改動(dòng)類別比如 feat: 新功能、fix: 修復(fù)問題、test: 測(cè)試相關(guān)、docs: 文檔修改。同時(shí)一個(gè) commit 盡量只做一件事把邏輯上獨(dú)立的修改拆成多個(gè) commit方便 reviewer 逐個(gè)審查。Git 操作層面有幾個(gè)建議。一是經(jīng)常拉取主分支的最新代碼及時(shí) rebase 以減少合并沖突二是在提交信息中用祈使句開頭比如 Fix double free in comm buffer而不是 Fixing 或 Fixed三是提交信息正文可以簡(jiǎn)單寫清楚為什么做這個(gè)修改以及實(shí)現(xiàn)的思路但不要寫廢話。4.2 代碼風(fēng)格與自檢清單在推上遠(yuǎn)端之前先在自己的分支上做一輪自檢這種自檢能大幅提高 PR 通過率。以 C 代碼為例重點(diǎn)檢查以下幾項(xiàng)。第一命名是否規(guī)范。HCCL 這類底層庫(kù)對(duì)命名風(fēng)格有嚴(yán)格要求變量名要能清晰表達(dá)含義避免 a、b、c 這種無(wú)意義命名函數(shù)和類的命名要符合項(xiàng)目既有風(fēng)格不要一種模塊用駝峰、一種用下劃線至少在同一個(gè)文件里保持一致。第二邊界條件是否處理。比如你改了一個(gè)緩沖區(qū)分配邏輯是否考慮了 size 為 0 的情況是否考慮了內(nèi)存對(duì)齊要求是否能處理分配失敗這些邊界條件往往是 bug 的溫床。第三是內(nèi)存和資源管理。C/C 項(xiàng)目最常見的問題就是內(nèi)存泄漏、雙重釋放、資源未釋放。如果你改動(dòng)的代碼涉及動(dòng)態(tài)內(nèi)存分配仔細(xì)檢查每條路徑上資源是否都被正確釋放。對(duì)于不熟悉 C 內(nèi)存管理的同學(xué)建議先讀幾遍項(xiàng)目里已有的分配釋放邏輯照葫蘆畫瓢比自由發(fā)揮更安全。第四日志是否恰當(dāng)。HCCL 有自己的日志系統(tǒng)在關(guān)鍵路徑和錯(cuò)誤分支上應(yīng)該有合理的日志輸出方便線上問題排查。但日志也不能太多每個(gè)正常操作都打一條日志會(huì)把性能拖垮。第五測(cè)試是否充分。如果改動(dòng)修復(fù)了某個(gè) bug至少應(yīng)該有一個(gè)能驗(yàn)證該 bug 被修復(fù)的測(cè)試用例。對(duì)于性能優(yōu)化則需要附上優(yōu)化前后的基準(zhǔn)測(cè)試結(jié)果。4.3 PR 描述怎么寫得讓 Reviewer 秒懂PR 描述是你和 reviewer 溝通的第一份材料它的質(zhì)量直接決定了 review 的順暢程度。一份好的 PR 描述不需要長(zhǎng)篇大論但必須覆蓋幾個(gè)核心信息這個(gè) PR 解決什么問題、改動(dòng)涉及哪些模塊、實(shí)現(xiàn)思路是什么、測(cè)試結(jié)果如何、是否有關(guān)聯(lián)的 Issue。一個(gè)比較實(shí)用的模板結(jié)構(gòu)如下## 背景 2~3 句話說清楚為什么要做這個(gè)修改關(guān)聯(lián)的 Issue 編號(hào) ## 改動(dòng)內(nèi)容 列出主要改動(dòng)文件和每個(gè)文件的核心變更點(diǎn) ## 實(shí)現(xiàn)思路 簡(jiǎn)要說明采用的技術(shù)方案為什么選擇這個(gè)方案而不是其他方案 ## 測(cè)試驗(yàn)證 本地測(cè)試、單測(cè)、CI 結(jié)果、性能對(duì)比數(shù)據(jù) ## 影響范圍 這個(gè)改動(dòng)會(huì)影響哪些模塊或場(chǎng)景是否涉及接口變更、是否需要升級(jí)適配寫 PR 描述的時(shí)候要站在 reviewer 的角度去寫。reviewer 可能對(duì)你的改動(dòng)上下文不熟悉你要用最短的時(shí)間讓他理解你在做什么、為什么這么做。不要直接拷貝 commit message 到 PR 描述里commit message 是給代碼歷史看的PR 描述是給人看的兩者內(nèi)容可以有重疊但 PR 描述應(yīng)該更完整、更有邏輯。還有一點(diǎn)PR 描述里提到的測(cè)試結(jié)果一定要真實(shí)可查不要編造數(shù)字。如果某個(gè)性能數(shù)據(jù)是在特定條件下測(cè)出來(lái)的要如實(shí)寫明測(cè)試環(huán)境和方法。reviewer 大概率會(huì)追著你問數(shù)據(jù)的來(lái)源如果數(shù)據(jù)站不住腳你的信譽(yù)會(huì)大打折扣。5. 過 CI 和 Code Review 的硬仗5.1 CI 跑哪些東西提交 PR 之后代碼會(huì)自動(dòng)進(jìn)入 CI 流程。HCCL 的 CI 通常包括編譯檢查、單元測(cè)試、靜態(tài)代碼掃描、以及依賴于硬件環(huán)境的集成測(cè)試。你不一定能看到所有 CI 階段但編譯檢查和靜態(tài)掃描基本每次都會(huì)觸發(fā)。CI 失敗是每個(gè)貢獻(xiàn)者都會(huì)遇到的事情第一次不用慌。最常見的失敗原因有三類編譯錯(cuò)誤、代碼格式不符合規(guī)范、測(cè)試用例掛了。編譯錯(cuò)誤比較直觀順著日志里報(bào)錯(cuò)的文件和行號(hào)定位即可。格式問題則需要用項(xiàng)目指定的工具跑一遍自動(dòng)格式化比如 clang-format 或 astyle 之類格式化完成后再提交。測(cè)試用例失敗的情況需要具體分析。如果在本地能復(fù)現(xiàn)那就按正常的調(diào)試流程走如果本地?zé)o法復(fù)現(xiàn)則可能是環(huán)境差異導(dǎo)致的此時(shí)可以在 PR 評(píng)論中說明情況并請(qǐng)求維護(hù)者協(xié)助查看 CI 日志。有些 CI 失敗是因?yàn)榛A(chǔ)設(shè)施不穩(wěn)定導(dǎo)致的偶發(fā)失敗比如網(wǎng)絡(luò)超時(shí)、資源調(diào)度延遲這種情況下重跑一次就過了但如果是你的代碼引起的重跑多少次都是失敗。想減少 CI 往返次數(shù)最好的辦法是在本地盡量復(fù)現(xiàn) CI 的檢查項(xiàng)。比如提前在本地跑單元測(cè)試、靜態(tài)檢查、格式化校驗(yàn)確保這些過了再推代碼。CI 每失敗一次你的 PR 合入時(shí)間就延后一次而每個(gè)維護(hù)者一天能處理的 PR 數(shù)量是有限的。5.2 面對(duì) review 意見的心態(tài)與技術(shù)準(zhǔn)備Code review 是整個(gè)貢獻(xiàn)流程中壓力最大但也最有價(jià)值的環(huán)節(jié)。你的 PR 提交后維護(hù)者或社區(qū)成員會(huì)逐行查看代碼提出修改意見。這些意見可以是針對(duì)正確性的嚴(yán)重問題也可以是對(duì)變量命名的吹毛求疵甚至是對(duì)代碼風(fēng)格的偏執(zhí)。先說一個(gè)最重要的心態(tài)建設(shè)review 意見不是針對(duì)你一個(gè)人的它是針對(duì)代碼本身的?？吹健斑@里加個(gè)空指針檢查”這種意見不要興奮也不要失落把它當(dāng)作一次技術(shù)方案打磨的過程就好。技術(shù)準(zhǔn)備方面你要能區(qū)分不同性質(zhì)的 review 意見。如果是正確性問題比如并發(fā)競(jìng)爭(zhēng)、內(nèi)存錯(cuò)誤、邏輯漏洞這個(gè)沒有商量的余地務(wù)必認(rèn)真修改。如果是風(fēng)格和可讀性意見雖然不強(qiáng)制但建議盡量順從因?yàn)榫S護(hù)者比你更了解項(xiàng)目的歷史慣性和后續(xù)維護(hù)成本。如果是方案層面的討論比如“你為什么會(huì)選擇用自旋鎖而不是互斥鎖”這種意見開放度比較高你可以從實(shí)際場(chǎng)景和性能測(cè)試數(shù)據(jù)出發(fā)據(jù)理力爭(zhēng)前提是你的論證有數(shù)據(jù)支撐。有個(gè)經(jīng)驗(yàn)可以分享當(dāng)你在 review 中修改代碼之后一定要在 PR 評(píng)論區(qū)回復(fù)每條意見的處理結(jié)果。常見的做法是直接用 GitHub/Gitee 的回復(fù)功能加一段“已修復(fù)見 commit xxxxxxx”或者“這個(gè)建議我不太認(rèn)同原因是……”。每個(gè)意見都有交代reviewer 才能放心地在后續(xù) commit 中只關(guān)注新增的改動(dòng)。5.3 反復(fù)修改與歷史清理除非你寫代碼真的行云流水否則一個(gè) PR 經(jīng)過多輪 review 修改是非常普遍的事情。每輪修改之后你需要在 PR 里追加新的 commit。這里有一個(gè)困擾很多新手的問題我改了一輪產(chǎn)生了 3 個(gè)新 commit歷史能清理嗎我的建議是分階段處理。在你的 PR 還沒有被 reviewer 大量關(guān)注之前可以用 git rebase 把多個(gè)小 commit 合并成幾個(gè)邏輯完整的 commit讓歷史保持整潔。但當(dāng) reviewer 已經(jīng)在舊 commit 上留過言之后就不要再隨意 rebase 了因?yàn)槟菚?huì)讓 review 評(píng)論和代碼版本對(duì)不上反而增加溝通成本。這個(gè)階段你可以通過追加 commit 的方式表達(dá)等 PR 合入時(shí)平臺(tái)一般會(huì)默認(rèn)用 squash merge 的方式把整個(gè) PR 壓成一個(gè) commit這樣最終歷史依然干凈。Git 操作上還有一個(gè)注意項(xiàng)rebase 時(shí)不要強(qiáng)推git push --force已經(jīng)公開的 commit如果你用了一定要在 PR 評(píng)論里明確告知否則別人本地的分支會(huì)變得非?；靵y。更穩(wěn)妥的做法是先 fetch 主分支最新代碼然后 rebase 到最新再?gòu)?qiáng)推你的 PR 分支。5.4 合入前最后一道關(guān)卡簽署與自評(píng)很多開源項(xiàng)目在 PR 正式合入前還有一個(gè)輕量級(jí)的合規(guī)檢查常見的是貢獻(xiàn)者許可協(xié)議CLA和開發(fā)者原創(chuàng)證書DCO。HCCL 這類商業(yè)驅(qū)動(dòng)的開源項(xiàng)目通常都在意這種合規(guī)問題因?yàn)樗婕按a的版權(quán)歸屬和法律風(fēng)險(xiǎn)。如果合入前提示你需要簽署 CLA不要覺得麻煩這是一條一次性流程填一遍以后所有項(xiàng)目都能通用。DCO 的簽署則更簡(jiǎn)單一般只需要在你的 commit message 尾部追加一行 Signed-off-by: 你的名字 郵箱表示你確認(rèn)這些代碼是你寫的或者你有權(quán)提交這些代碼。很多新手一看到英文縮寫就以為很復(fù)雜其實(shí)整個(gè)流程五分鐘內(nèi)就能完成。還有一個(gè)容易被忽略的步驟合入前自己最后讀一遍完整的 diff。尤其是改動(dòng)后的文件從 Git 的 diff 視角再審視一次。你會(huì)發(fā)現(xiàn)很多平時(shí)注意不到的小問題,比如誤提交的調(diào)試代碼、多余的空白改動(dòng)、臨時(shí)的日志輸出。自己先把這些問題清理干凈再讓維護(hù)者看到能少挨很多批。6. 合入之后與常見問題速查6.1 合入不是終點(diǎn)PR 合入之后很多人會(huì)覺得這件事結(jié)束了可以接著去做下一個(gè)任務(wù)。但從貢獻(xiàn)者的角度合入只是開始真正驗(yàn)證你改動(dòng)的時(shí)刻是在之后的一個(gè)月。首先你要關(guān)注合入后的 CI 情況。合入主分支并不意味著代碼完全沒問題穩(wěn)健的項(xiàng)目通常會(huì)在主分支上跑更長(zhǎng)時(shí)間、更全面的回歸測(cè)試。如果這些測(cè)試發(fā)現(xiàn)你引入了回歸維護(hù)者會(huì)在你的 PR 討論里回復(fù)你或者新建一個(gè) Issue 指向你的提交。其次你可以繼續(xù)保持對(duì)相關(guān) Issue 的關(guān)注。如果你的改動(dòng)修復(fù)了某個(gè)用戶報(bào)告的 bug可以留意用戶側(cè)有沒有反饋“這個(gè)修復(fù)有效”或“問題仍然存在”的信息。如果問題仍然存在你需要重新打開 Issue 繼續(xù)排查這也是開源社區(qū)協(xié)作的正常節(jié)奏。另外作為一個(gè)已經(jīng)合入過代碼的貢獻(xiàn)者你已經(jīng)有資格去 review 別人的 PR 了。這是一個(gè)很好的學(xué)習(xí)機(jī)會(huì)——你會(huì)發(fā)現(xiàn)坐在 reviewer 的位置上你會(huì)更加理解那些你曾經(jīng)覺得煩瑣的規(guī)范其實(shí)都是項(xiàng)目質(zhì)量和可維護(hù)性的保證。6.2 常見問題速查表下面整理了一些 HCCL 貢獻(xiàn)過程中常見的問題和排查方向是我以及身邊同事實(shí)際踩過的坑供你參考。問題現(xiàn)象可能原因排查思路本地編譯失敗報(bào)缺少頭文件依賴庫(kù)路徑未配置檢查 CANN 或驅(qū)動(dòng)環(huán)境變量確認(rèn) LD_LIBRARY_PATH 是否正確CI 失敗全部失敗在編譯階段拉取代碼時(shí)未同步子模塊檢查倉(cāng)庫(kù)是否用 --recurse-submodules 拉取或手動(dòng)更新子模塊CI 失敗失敗在靜態(tài)掃描代碼格式不符合規(guī)范本地運(yùn)行 clang-format 等格式化工具后重新提交本地單測(cè)通過CI 單測(cè)失敗環(huán)境差異或測(cè)試數(shù)據(jù)不同對(duì)比本地與 CI 的環(huán)境變量、依賴版本必要時(shí)在 PR 中請(qǐng)求維護(hù)者獲取 CI 日志性能優(yōu)化數(shù)據(jù)不佳方案與硬件拓?fù)洳黄ヅ鋰L試在不同卡數(shù)、不同數(shù)據(jù)量下進(jìn)行基準(zhǔn)測(cè)試分析是否引入了不必要的同步無(wú)法在本地復(fù)現(xiàn) Issue 中的崩潰缺少日志開關(guān)或特定環(huán)境變量按 Issue 中提供的信息逐項(xiàng)核對(duì)尤其是數(shù)據(jù)量、拓?fù)浜万?qū)動(dòng)版本PR 長(zhǎng)期無(wú)人 review維護(hù)者繁忙或描述不清晰在 PR 評(píng)論區(qū)禮貌 維護(hù)者或補(bǔ)充測(cè)試數(shù)據(jù)和復(fù)現(xiàn)步驟讓問題更清晰6.3 幾條值得謹(jǐn)記的避坑心得做了一段時(shí)間 HCCL 貢獻(xiàn)之后有幾個(gè)踩過的坑讓我印象很深這里集中說一下。第一不要在 issue 里只問“怎么解決”而不提供任何上下文。一個(gè)好的問題應(yīng)該讓人感覺你已經(jīng)讀過代碼、有自己的猜測(cè)只需要?jiǎng)e人幫你確認(rèn)方向。我在社區(qū)里看到過的最高效的一次提問是一個(gè)貢獻(xiàn)者直接貼出了他定位到的代碼行號(hào)并附上了他對(duì)問題的分析維護(hù)者只回了一句“你的判斷是對(duì)的修吧”這比來(lái)回追問五六輪高效太多。第二不要在一個(gè) PR 里同時(shí)修多個(gè)不相關(guān)的問題。多個(gè)問題混在一起reviewer 很難評(píng)估風(fēng)險(xiǎn)。一個(gè) PR 解決一個(gè)問題是開源協(xié)作的基本契約。如果你發(fā)現(xiàn)代碼里另外有一個(gè) bug請(qǐng)新建一個(gè) Issue 或者再開一個(gè) PR不要塞到當(dāng)前這個(gè)里。第三不要忽視文檔的力量。代碼改動(dòng)如果涉及對(duì)外行為的變化比如環(huán)境變量語(yǔ)義變更、接口參數(shù)調(diào)整、日志輸出變化一定同步更新相關(guān)文檔。你維護(hù)的不只是代碼還有這個(gè)項(xiàng)目的可理解性。很多 PR 因?yàn)槲臋n沒有同步更新而被要求返工這種事情完全可以提前避免。第四不要在 rebase 的過程中引入重復(fù)的改動(dòng)。很多新手在 rebase 主分支時(shí)因?yàn)闆_突解決不當(dāng)把主分支的代碼又復(fù)制了一份到自己分支里導(dǎo)致 diff 里出現(xiàn)大量無(wú)關(guān)改動(dòng)。遇到這種情況建議用 git diff 對(duì)比主分支和自己分支的差異檢查是否只保留了你想要改動(dòng)的文件。最后再說一點(diǎn)參與開源項(xiàng)目不是一個(gè)零和博弈。你可能提交的第一個(gè) PR 會(huì)被拒絕會(huì)被告知設(shè)計(jì)欠妥甚至?xí)蝗苏f“這個(gè)思路根本不對(duì)”。這些都很正常很多資深開發(fā)者當(dāng)年的第一個(gè) PR 也是被反復(fù)打回來(lái)的。關(guān)鍵是你能從反饋里學(xué)到東西而不是被打擊之后就放棄。如果你手頭有昇騰設(shè)備又有興趣深入了解分布式訓(xùn)練底層的通信邏輯可以試著從跑通官方 benchmark 開始然后自己設(shè)置一些異常數(shù)據(jù)或者異常環(huán)境變量看看會(huì)發(fā)生什么。好奇心是最好的入口而 Issue 和 PR 只是把你對(duì)問題的理解轉(zhuǎn)化成最終代碼的載體。只要你能把一件事寫清楚、說清楚、改清楚開源社區(qū)的大門對(duì)你就是敞開的。