提交程式碼變更

本頁面說明將程式碼變更內容提交至 Android 開放原始碼專案 (AOSP) 的完整程序，包括如何要求審查及追蹤變更內容。

AOSP 會使用 Gerrit，這是專為使用 Git 的專案提供的網頁式程式碼審查系統。

簽署貢獻者授權協議

為 AOSP 提供任何程式碼變更之前，您必須閱讀貢獻者授權協議和標頭，並簽署下列任一協議：

• 身為僅代表您提供貢獻的個人貢獻者，請簽署個人貢獻者授權協議。
• 如果你是企業員工，請確認貴公司已簽署企業貢獻者授權協議，授權你代表公司做出貢獻。

注意： 如要變更 Android 使用的上游專案，您必須直接對該專案進行變更。詳情請參閱「為上游專案做出貢獻」。

開始分支

針對每個要變更的程式碼，請執行下列步驟：

1. 在相關 Git 存放區中開始新的分支。分支並非原始檔案的副本，而是指向特定版本的指標，因此建立本機分支並在分支之間切換，可輕鬆完成。使用分支後，您就能辨識各個分支的變更。執行以下指令即可開始建立分支：

   repo start BRANCH_NAME

   您可以在同一個存放區中同時啟動多個獨立的分支。分支 BRANCH_NAME 是工作區的本機分支，不會納入 Gerrit 或最終來源樹狀結構。分支也適用於您所在的專案，因此如果您需要在不同專案中變更檔案，以便進行相同變更，則每個變更檔案的專案都需要分支。

2. (選用) 確認分支版本是否已建立：

   repo status .

   您應該會看到新建立的分支。例如：

   project frameworks/native/                      branch mynewbranch

   注意： 您也可以使用 repo branches 取得所有分支的清單，其中目前的分支 (如有) 前方會加上星號 (*)。

進行變更並進行測試

請按照下列步驟進行變更並進行測試：

1. 為確保您使用的是最新的程式碼集，請同步整個程式碼集：

   repo sync

   注意： 如要只同步處理目前的專案，請在 repo sync 指令中加入一個句號 (.)：repo sync .。同步處理目前專案的速度，會比同步處理整個存放區還快。

   如果在同步處理期間發生任何衝突，請參閱「解決同步處理衝突」中的步驟 2 至 4。

2. 找出要變更的程式碼。如要尋找程式碼，建議您使用 Android Code Search。您可以使用 Android Code Search 查看 AOSP 原始碼，因為該程式碼會按照實際使用時的版面配置顯示。詳情請參閱「開始使用 Code Search」。如要在 Android Code Search 中查看最新 AOSP 發布分支中的所有程式碼，請前往 https://cs.android.com/android/platform/superproject/。

3. 修改或新增來源檔案。如有任何變更：

   • 判斷是否需要使用功能啟動標記，如果需要，請為新程式碼導入這些標記。

   • 請遵循「加入授權標頭」中的最佳做法。

   • 如要編寫 Java 程式碼，請遵循 AOSP Java 程式碼風格 (供貢獻者使用)。

   • AOSP 的部分內容是以 Kotlin (.kt) 編寫，您可以在已以 Kotlin 編寫的平台部分使用 Kotlin。如要進一步瞭解 Android 中的 Kotlin，請參閱 Android 開發人員適用的 Kotlin 樣式指南和 Kotlin-Java 互通性指南。如需更詳盡的 Kotlin 指南，請參閱 Kotlin 語言網站。

   • 編寫 API 時，請遵循 Android API 指南。您可以參考這些指南，瞭解 Android 的 API 決策背後的背景。Metalava 會驗證平台 API 的新增和修改內容。

4. 建構 Android。

5. 測試建構作業。

階段化並提交變更

提交是 Git 中修訂版本控制的基本單位，包含整個專案的目錄結構和檔案內容快照。請按照下列步驟提交變更：

1. 根據預設，Git 會註冊但不會追蹤您所做的變更。如要指示 Git 追蹤變更，您必須標記或暫存這些變更，以便納入版本控制。執行以下指令來排程變更：

   git add -A

   這個指令會追蹤您對任何檔案所做的變更。

   注意：如果您只想追蹤特定檔案的變更，請使用 git add filename。
   注意：除了追蹤檔案變更，git add 還可用於執行其他作業，例如修改和刪除暫存檔。

2. 將暫存區中的檔案提交或儲存在本機資料庫中：

   git commit -s

   根據預設，系統會開啟文字編輯器，並提示您提供提交訊息。

3. 請以下列格式提供修訂訊息：

   • 第 1 行：標題。提供變更內容的摘要 (最多 50 個半形字元)。建議您使用前置字串來說明變更的區域，接著說明您在這個版本中所做的變更，例如以下包含使用者介面變更的範例：

     ui: Removes deprecated widget
     

   • 第 2 行：空白行。標題後面要加上空白行。

   • 第 3 行：主體。提供詳細說明，最多可使用 72 個半形字元。說明變更解決了什麼問題，以及如何解決。雖然內容為選用項目，但對於需要參照變更內容的其他人來說，這項資訊非常實用。請務必附上簡短的註解，說明任何假設或背景資訊，這些資訊可能在其他作者處理這項功能時相當重要。

   如要閱讀有關良好提交說明的文章 (附範例)，請參閱「如何撰寫 Git 提交訊息」。

4. 儲存修訂版本。

系統會自動將不重複的變更 ID 和您在 repo init 期間提供的姓名和電子郵件地址，加入至您的提交訊息。

上傳變更項目以供審查

將變更提交至個人 Git 記錄後，請將其上傳至 Gerrit：

1. 執行下列指令，上傳所有專案中的所有提交內容：

   repo upload

   上傳內容會包含所有專案的所有變更。

   注意：如要只上傳目前專案中的變更，請在 repo upload 指令中加入一個句號 (.)：repo upload .。
   注意：如果您正在處理的變更需要變更多個專案中的檔案，請使用 Gerrit 中的主題將變更連結在一起，無論您使用 repo upload 或 repo upload . 皆然。Gerrit 主題可確保變更會保留在一起，以便在提交前進行測試，並透過自動合併功能進行測試。詳情請參閱「使用主題」

   系統會提示您執行掛鉤指令碼。

2. 依序按下 a 鍵和 Enter 鍵。

   系統會提示您核准上傳作業：

   Upload project frameworks/native/ to remote branch android15-qpr2-release:
   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)?
   

   注意： 如果您在同一個存放區中啟動多個分支，系統會提示您選取要上傳的分支，方法是在文字編輯器中取消註解這些分支。

3. 按下 y 鍵，然後按下 Enter 鍵，即可核准上傳作業。

您應該會收到類似 remote: SUCCESS 的訊息。

申請審查

上傳成功後，Repo 會提供 Gerrit 中變更項目的連結。按一下連結即可在審查伺服器上查看變更內容、新增註解，或要求特定審查人員審查變更內容。程式碼的所有變更都必須由適當的程式碼擁有者審查。

注意： AOSP 中包含的版本設定是由 Google 定義。Google 不接受更新或變更設定的功能發布旗標的貢獻。您可以改為定義自訂版本設定，包括 AOSP 分支版本中的預設標記值。如要進一步瞭解版本設定，請參閱「設定功能啟動旗標值」。

提出審查要求的步驟如下：

1. 在 Gerrit 中，按一下「建議擁有者」：

   

   圖 1. 建議在 Gerrit 中提供擁有者連結。

   系統隨即會顯示審查員對話方塊。這個對話方塊會列出可審查變更的程式碼擁有者。

2. 按一下程式碼擁有者，將他們加入審查。

   注意： 如要瞭解如何判斷擁有者，請參閱 find-owners 後端。

   系統會啟用「SEND」按鈕。

3. (選用) 輸入您想請其他人審查變更內容的電子郵件地址。

4. 按一下「傳送」，將變更內容送審。

程式碼擁有者會審查您的程式碼變更，如果接受，就會挑選變更並合併至內部開發分支。

判斷變更狀態

如要判斷變更中的檔案狀態，請檢查變更中檔案旁的以下圖示：

• (核取記號圖示)：程式碼擁有者已核准
• (十字圖示)：程式碼擁有者未核准
• (時鐘圖示)：等待程式碼擁有者核准

下圖顯示在變更中套用至檔案的狀態圖示：

圖 2. 檔案範例：顯示程式碼擁有者核准狀態的圖示。

解決意見回饋並上傳替換變更

如果審查人員要求您修改更新內容，您可以在 Git 中修改修訂版本，這會在相同變更上產生新的修補程式集。

注意： 如果您在上傳變更後建立其他分支並進行其他提交，則很可能會在其中一個分支中進行工作，而非原始變更的分支。因此，您必須先使用 repo start EXISTING_BRANCH_NAME 指令前往該分支，才能解決原始分支的意見回饋。

如要解決意見回饋並修改變更內容，請按照下列步驟操作：

1. 請按照「進行變更並進行測試」中的步驟 2 至 4 操作。

2. 執行下列指令來修改變更：

   git add -A
   git commit --amend

3. 上傳變更內容。

當您上傳修訂版變更時，該變更會取代 Gerrit 和本機 Git 歷程中的原始版本。

解決同步處理衝突

如果其他變更與您提交至來源樹狀結構的變更相衝突，您會收到有衝突的訊息。如要解決衝突問題，請按照下列步驟操作：

1. 請確認您使用的是最新的程式碼：

   repo sync .

   repo sync 指令會從來源伺服器擷取更新，然後嘗試自動將 HEAD 重新命名至新的遠端 HEAD。

2. 如果自動重新定基失敗，請手動重新定基：

   repo rebase .

3. 解決合併衝突。如果您沒有偏好的解決合併衝突的方法，可以使用 git mergetool 手動修正檔案之間的衝突。

4. 成功修正衝突檔案後，請執行以下指令套用新的提交內容：

   git rebase --continue

提交變更

提交內容通過審查和驗證程序後，程式碼擁有者會為您提交程式碼，可提交至變更經過審查的分支版本，或提交至內部分支版本。

提交內容完成合併後，您可以前往 Android Continuous Integration 資訊主頁，監控提交內容何時整合至樹狀結構。