為 OpenXLA 貢獻心力

每個人都能協助 OpenXLA,我們十分重視每位員工的貢獻。您可以透過多種方式貢獻內容,包括:

  • 在 OpenXLA 的論壇 (openxla-討論) 上回答問題

  • 改善或擴充 OpenXLA 說明文件

  • 協助改善 OpenXLA 的程式碼集

  • 以上述任一方式貢獻內容給在 OpenXLA 上建構的更廣大的程式庫生態系統

OpenXLA 專案遵循 Google 的開放原始碼社群規範

事前準備

簽署《貢獻者授權協議》

為這項專案做出貢獻時必須遵守《貢獻者授權協議》(CLA)。您 (或您的雇主) 保留對於您的貢獻的版權,這只是授權我們在專案中使用和重新分配您的貢獻。

如果您或您目前的雇主已經簽署 Google CLA (即便是供其他專案使用),則可能不必重新執行。

請造訪 <https://cla.developers.google.com/> 查看您目前的協議,或是簽署新協議。

查看行為準則

本專案遵循 Tensorflow 的行為準則

捐款程序

開發人員指南

如要瞭解如何設定 OpenXLA 的開發環境,包括取得程式碼、建構開發環境、執行測試及提交變更,請參閱開發人員指南

程式碼標準

  • 程式設計樣式:請按照 Google 程式碼樣式指南的說明操作。具體來說,請參閱 C/C++Python 指南。提交的所有程式碼都必須嚴格遵守這些樣式指南。

  • 密集變更:我們會遵循 Google 的工程做法。請特別留意撰寫密集變更的說明指南。這麼做將可大幅加快程式碼合併的速度,提升審查性,並降低變更產生意外副作用的可能性。即使您有重大變更,還是有許多策略能將其細分為更多增量變更。

  • 測試涵蓋範圍:所有變更都必須包含適當的單元測試。單元測試不應仰賴特定硬體 (CPU、GPU 等) 時間,並應精確地使用模擬和假象,以便進行確定性且聚焦的測試。如果變更是為了擴充目前難以測試的現有程式碼,則應針對可測試性做出適當改善。

    所有變更都應該在變更標題中附上適當的基準結果,以確保清楚瞭解好處。

  • 如對程式碼中的慣例有疑慮時,建議您檢查現有的程式碼,並嘗試遵循 OpenXLA 中既有的模式。

審核程序

所有提交內容 (包括專案成員所提交的提交內容) 都必須經過審核。為達成這個目的,我們使用 GitHub 提取要求。如要進一步瞭解如何使用提取要求,請參閱 GitHub 說明

  • 程式碼必須符合上述所有標準才能審查。這些並非選擇性,而且提交者務必先確認其程式碼符合規範,再提出審查要求,以確保及時接受變更。

  • 所有測試必須通過。如果您發現測試故障,且問題與建構環境或其他變更無關,請與維護人員聯絡。

  • 避免在審查過程中規避範圍。這是提交者和審查者的責任。如果變更開始變得太大,請考慮將變更拆分為多項變更。

  • 合併變更之前,需要進行內部測試,該測試會使用 Google 和其他硬體供應商內部的程式碼。如果公用 CI 無法偵測出的內部測試失敗,這可能在審查程序中新增額外的步驟。審查變更的 Google 員工會告知所有內部測試失敗情形,並說明需要修正的內容。

常見問題 (FAQ)

XLA 團隊沒有專屬的基礎架構團隊,因此我們要共同打造輔助程式庫,避免產生技術債。我們認為這是 XLA 變更的一環,而且每個人都應該參與。一般來說,我們會在編寫程式碼時視需要建構基礎架構。

XLA 審查人員可能會要求您建構一些基礎架構 (或對 PR 進行重大變更) 以及您已撰寫的 PR。這項要求似乎與您嘗試的變更可能無關或無關緊要。這可能是因為您需要建構多少基礎架構,以及審查者對相同情況的期望不符。

說不定並沒有什麼意思!這是您剛開始使用專案時應有的感覺 (有時甚至可能跟我們老帽有關)。您過去處理過的專案 可能會有不同的期望這也沒關係 我們預期你這麼做這並不表示這兩個專案的執行方法有誤:歡迎您提出基礎架構要求以及所有其他審查評論,瞭解我們對這項專案的期望。

「我可以在未來 PR 中解決你的留言嗎?」

在 PR 中,基礎架構要求 (或其他大型要求) 的一個常見問題是變更是否必須在原始 PR 中進行,或者是否能在日後的 PR 中以後續追蹤方式完成。

一般來說,XLA 不允許 PR 作者透過後續追蹤 PR 處理評論留言。當審查人員判定某件事需要在指定的 PR 中處理時,我們一般會預期作者在該 PR 中處理這個問題,即使要求的內容是很大的變更亦然。這項標準適用於外部,也適用於 Google 內部。

有幾個原因會讓 XLA 採用此方法。

  • 信任度:贏得評論者的信任是關鍵要素。在開放原始碼專案中,貢獻者可自由顯示或隱藏。我們核准 PR 後,審查人員就無法確保任何承諾的後續追蹤確實完成。

  • 對其他開發人員的影響:如果您傳送 PR 接觸 XLA 的特定部分,很有可能會有人看到相同的部分。如果我們在您的公關部門接受技術債務,則所有查看這個檔案的所有使用者都會受到此債務影響,直到提交後續追蹤為止。

  • 審查人員頻寬:延後變更後續作業,可能會對我們的超載審查人員造成多筆費用。在等待後續審查的過程中,審查員可能會忘記第一則 PR 的內容,使得下次審查變得更困難。除此之外,審查員也必須追蹤預期的後續後續情形,確保這些內容能確實發生。如果變更內容能使其與原始 PR 完全無關,以便讓其他審查人員查看,則頻寬可能就不那麼問題。就我們的經驗而言,這種情況很少見。