提交程式碼變更

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

Android 開放原始碼計畫需要使用 Gerrit，這是網頁式的程式碼審查系統，適用於使用 Git 的專案。

簽署協作者授權協議

提供 Android 開放原始碼計畫的任何程式碼變更之前，請務必閱讀貢獻者授權協議和標頭，並簽署下列其中一項協議：

• 以個人名義貢獻內容的個人貢獻者，請簽署個人貢獻者授權協議。
• 身為任職公司的員工，請確認貴公司已簽署企業貢獻者授權協議，授權您代為做出貢獻。

建立分支版本

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

1. 在相關的 Git 存放區中啟動新的分支版本。分支版本並非原始檔案的複本，而是指向特定修訂版本的指標，會使建立本機分支版本並在之間進行切換的輕量作業。您可以使用分支版本來識別彼此的變更。執行下列指令來啟動分支版本：

   repo start BRANCH_NAME
   

   您可以同時在同一個存放區中啟動多個獨立的分支版本。分支版本 BRANCH_NAME 是工作區本機，不會包含在 Gerrit 或最終來源樹狀結構中。分支也專屬於您所在的專案，因此如果您需要變更不同專案中的檔案做為相同變更的一部分，您必須在每個要變更檔案的專案中建立分支。

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

   repo status .
   

   您應該會看見新建立的分支版本。舉例來說：

   project frameworks/native/                      branch mynewbranch
   

進行變更並測試變更

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

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

   repo sync
   

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

2. 找出要變更的程式碼。如要尋找程式碼，建議您使用 Android 程式碼搜尋功能。您可以使用 Android 程式碼搜尋查看 Android 開放原始碼計畫的原始碼，就像實際使用時一樣。詳情請參閱「開始使用程式碼搜尋」一文。如要查看 Android 程式碼搜尋中 main 分支版本的所有程式碼，請前往 https://cs.android.com/android/platform/superproject/main。

3. 修改或新增來源檔案。進行的任何變更：

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

   • 如為 Java 程式碼，請參閱「協作者適用的 Android 開放原始碼計畫 Java 程式碼樣式」。

   • Android 開放原始碼計畫的某些部分是以 Kotlin (.kt) 編寫，而您可以在採用 Kotlin 編寫的平台領域中使用 Kotlin。如要進一步瞭解 Android 中的 Kotlin，請參閱 Android 開發人員 Kotlin 樣式指南和 Kotlin-Java 互通性指南。如需更詳盡的 Kotlin 指南，請參閱 Kotlin 語言網站。

   • 編寫 API 時，請遵守 Android API 規範。您可以參考這些指南，瞭解 Android API 決策背後的背景資訊。平台 API 的新增和修改作業均由 Metalava 驗證。

4. 建構 Android。

5. 測試版本。

暫存及提交變更

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

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

   git add -A
   

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

2. 接著從暫存區域中提交檔案，或將檔案儲存在您的本機資料庫中：

   git commit -s
   

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

3. 請使用下列格式的修訂訊息：

   • 第 1 行：廣告標題。請提供一行變更的摘要 (最多 50 個字元)。請考慮使用前置字串來描述已變更的區域，然後說明您在這個修訂版本中所所做的變更 (例如以下含有使用者介面變更的範例)：

     ui: Removes deprecated widget
     

   • 第 2 行：空白行。然後接續使用空白行。

   • 第 3 行：內文。提供詳細說明，不要超過 72 個半形字元。說明改變可以解決的問題以及解決方法。雖然內文是選擇性的，但對需要參考變更的其他人而言非常實用。如果其他貢獻者參與這項功能時，您可能需要做出一些相關的假設或背景資訊，請務必簡短附註。

   如要閱讀有關良好修訂版本說明 (含範例) 的網誌，請參閱如何編寫 Git 修訂版本訊息。

4. 儲存修訂版本。

系統會自動將不重複的變更 ID，以及您在 repo init 期間提供的名稱和電子郵件地址加到修訂訊息中。

上傳變更以供審查

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

1. 執行下列指令，上傳所有專案中的所有修訂版本：

   repo upload
   

   所有專案中的所有變更都會納入上傳作業。

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

2. 按下 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)?
   

3. 依序按下 Y 鍵和 Enter 鍵，即可核准上傳作業。

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

提出審核要求

上傳成功後，Repo 會提供您顯示在 Gerrit 中變更的連結。按一下連結即可在審查伺服器上查看變更、新增註解，或要求特定審查人員進行變更。對程式碼所做的所有變更都必須經過相關的程式碼擁有者審查。申請審查的步驟如下：

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

   

   圖 1 在 Gerrit 中推薦擁有者連結。

   畫面上隨即會顯示審查者對話方塊。此對話方塊列出可以審查變更的程式碼擁有者。

2. 按一下程式碼擁有者，將對方加進評論。

   「傳送」按鈕已啟用。

3. (選填) 輸入可審查變更的其他人電子郵件地址。

4. (選用) 按一下「自動提交」旁的「+1」，即可在獲得核准後自動提交變更。如果未點選這個按鈕，Google 員工就必須為您提交變更項目。

5. 按一下「傳送」將變更送審。

程式碼擁有者會審查程式碼變更，然後提供意見回饋來解決或核准變更。

判斷變更狀態

如要判斷變更內容檔案的狀態，請查看相關檔案旁是否有下列圖示：

• done (勾號圖示)：經過程式碼擁有者核准
• clear (交叉圖示)： 未經程式碼擁有者核准
• access_time (時鐘圖示)：正在等待程式碼擁有者核准

下圖顯示了變更中檔案所套用的狀態圖示：

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

解決意見回饋並上傳替換品

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

如何解決意見回饋並修改變更內容：

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
   

提交變更

提交內容會經過審查和驗證程序，Google 審查人員必須為您提交程式碼。其他使用者可以執行 repo sync，將更新提取到各自的本機用戶端中。

合併提交內容後，您可以前往 Android 持續整合資訊主頁，監控提交項目何時整合至樹狀結構中。