本頁說明向 Android 開放原始碼計畫 (AOSP) 提交程式碼變更的完整程序,包括如何要求審查及追蹤變更內容。
Android 開放原始碼計畫需要使用 Gerrit,這是網頁式的程式碼審查系統,適用於使用 Git 的專案。
簽署協作者授權協議
提供 Android 開放原始碼計畫的任何程式碼變更之前,請務必閱讀貢獻者授權協議和標頭,並簽署下列其中一項協議:
建立分支版本
針對每個您要變更的程式碼,執行下列步驟:
在相關的 Git 存放區中啟動新的分支版本。分支版本並非原始檔案的複本,而是指向特定修訂版本的指標,會使建立本機分支版本並在之間進行切換的輕量作業。您可以使用分支版本來識別彼此的變更。執行下列指令來啟動分支版本:
repo start BRANCH_NAME
您可以同時在同一個存放區中啟動多個獨立的分支版本。分支版本 BRANCH_NAME 是工作區本機,不會包含在 Gerrit 或最終來源樹狀結構中。分支也專屬於您所在的專案,因此如果您需要變更不同專案中的檔案做為相同變更的一部分,您必須在每個要變更檔案的專案中建立分支。
(選用) 確認分支版本已建立:
repo status .
您應該會看見新建立的分支版本。舉例來說:
project frameworks/native/ branch mynewbranch
進行變更並測試變更
請按照下列步驟進行變更並測試變更:
為確保您使用的是最新的程式碼集,請執行整個程式碼集的同步處理:
repo sync
如果同步處理期間發生任何衝突,請參閱解決同步處理衝突的步驟 2 到步驟 4。
找出要變更的程式碼。如要尋找程式碼,建議您使用 Android 程式碼搜尋功能。您可以使用 Android 程式碼搜尋查看 Android 開放原始碼計畫的原始碼,就像實際使用時一樣。詳情請參閱「開始使用程式碼搜尋」一文。如要查看 Android 程式碼搜尋中
main
分支版本的所有程式碼,請前往https://cs.android.com/android/platform/superproject/main
。修改或新增來源檔案。進行的任何變更:
- 請遵循「包含授權標頭」中的最佳做法。
如為 Java 程式碼,請參閱「協作者適用的 Android 開放原始碼計畫 Java 程式碼樣式」。
Android 開放原始碼計畫的某些部分是以 Kotlin (
.kt
) 編寫,而您可以在採用 Kotlin 編寫的平台領域中使用 Kotlin。如要進一步瞭解 Android 中的 Kotlin,請參閱 Android 開發人員 Kotlin 樣式指南和 Kotlin-Java 互通性指南。如需更詳盡的 Kotlin 指南,請參閱 Kotlin 語言網站。編寫 API 時,請遵守 Android API 規範。您可以參考這些指南,瞭解 Android API 決策背後的背景資訊。平台 API 的新增和修改作業均由 Metalava 驗證。
測試版本。
暫存及提交變更
修訂版本是 Git 中的修訂版本控管基本單位,內含整個專案的目錄結構和檔案內容數據匯報。 請按照下列步驟提交變更:
根據預設,Git 會註冊但不會追蹤您所做的變更。如要指示 Git 追蹤您的變更,您必須將這些變更標記或暫存,以納入修訂版本。執行下列指令來暫存變更:
git add -A
這個指令會追蹤您對任何檔案所做的變更。
接著從暫存區域中提交檔案,或將檔案儲存在您的本機資料庫中:
git commit -s
根據預設,系統會開啟文字編輯器,並提示您提供修訂訊息。
請使用下列格式的修訂訊息:
第 1 行:廣告標題。請提供一行變更的摘要 (最多 50 個字元)。請考慮使用前置字串來描述已變更的區域,然後說明您在這個修訂版本中所所做的變更 (例如以下含有使用者介面變更的範例):
ui: Removes deprecated widget
第 2 行:空白行。然後接續使用空白行。
第 3 行:內文。提供詳細說明,不要超過 72 個半形字元。說明改變可以解決的問題以及解決方法。雖然內文是選擇性的,但對需要參考變更的其他人而言非常實用。如果其他貢獻者參與這項功能時,您可能需要做出一些相關的假設或背景資訊,請務必簡短附註。
如要閱讀有關良好修訂版本說明 (含範例) 的網誌,請參閱如何編寫 Git 修訂版本訊息。
儲存修訂版本。
系統會自動將不重複的變更 ID,以及您在 repo init
期間提供的名稱和電子郵件地址加到修訂訊息中。
上傳變更以供審查
將變更提交至個人 Git 記錄後,請將變更上傳至 Gerrit:
執行下列指令,上傳所有專案中的所有修訂版本:
repo upload
所有專案中的所有變更都會納入上傳作業。
系統會提示您執行掛鉤指令碼。
按下 A 鍵,然後按下 Enter 鍵。
系統會提示您核准上傳:
Upload project frameworks/native/ to remote branch main: branch BRANCH_NAME ( 1 commit, Wed Aug 7 09:32:33 2019 -0700): ff46b36d android codelab change to https://android-review.googlesource.com/ (y/N)?
依序按下 Y 鍵和 Enter 鍵,即可核准上傳作業。
您應該會收到類似 remote: SUCCESS
的訊息。
提出審核要求
上傳成功後,Repo 會提供您顯示在 Gerrit 中變更的連結。按一下連結即可在審查伺服器上查看變更、新增註解,或要求特定審查人員進行變更。對程式碼所做的所有變更都必須經過相關的程式碼擁有者審查。申請審查的步驟如下:
在 Gerrit 中,按一下「SUGGEST OWNERS」(建議擁有者):
圖 1 在 Gerrit 中推薦擁有者連結。
畫面上隨即會顯示審查者對話方塊。此對話方塊列出可以審查變更的程式碼擁有者。
按一下程式碼擁有者,將對方加進評論。
「傳送」按鈕已啟用。
(選填) 輸入可審查變更的其他人電子郵件地址。
(選用) 按一下「自動提交」旁的「+1」,即可在獲得核准後自動提交變更。如果未點選這個按鈕,Google 員工就必須為您提交變更項目。
按一下「傳送」將變更送審。
程式碼擁有者會審查程式碼變更,然後提供意見回饋來解決或核准變更。
判斷變更狀態
如要判斷變更內容檔案的狀態,請查看相關檔案旁是否有下列圖示:
- (勾號圖示):經過程式碼擁有者核准
- (交叉圖示): 未經程式碼擁有者核准
- (時鐘圖示):正在等待程式碼擁有者核准
下圖顯示了變更中檔案所套用的狀態圖示:
圖 2. 顯示程式碼擁有者核准狀態的檔案範例。
解決意見回饋並上傳替換品
如果審查人員要求修改更新內容,您可以在 Git 內修改修訂版本,導致相同的變更產生新的修補程式集。
如何解決意見回饋並修改變更內容:
上傳修改後的變更時,會在 Gerrit 和本機 Git 記錄中取代原始檔案。
解決同步處理衝突
如果提交其他變更至來源樹狀結構與您的變更發生衝突,您會收到衝突訊息。如何解決衝突:
請確認您使用最新的程式碼:
repo sync .
repo sync
指令會從來源伺服器擷取更新,然後嘗試將HEAD
自動重新底座至新的遠端HEAD
中。如果自動重新計算失敗,請執行手動重新集:
repo rebase .
解決合併衝突。如果您沒有偏好的方法解決合併衝突,可以使用
git mergetool
手動修正檔案之間的衝突。成功修正衝突的檔案後,請執行下列指令來套用新的修訂版本:
git rebase --continue
提交變更
提交內容會經過審查和驗證程序,Google 審查人員必須為您提交程式碼。其他使用者可以執行 repo sync
,將更新提取到各自的本機用戶端中。
合併提交內容後,您可以前往 Android 持續整合資訊主頁,監控提交項目何時整合至樹狀結構中。