提交程式碼變更

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

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

簽署貢獻者授權協議

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

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

開始分支

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

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

   repo start BRANCH_NAME
   

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

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

   repo status .
   

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

   project frameworks/native/                      branch mynewbranch
   

進行變更並進行測試

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

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

   repo sync
   

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

2. 找出要變更的程式碼。如要尋找程式碼，建議您使用 Android Code Search。您可以使用 Android Code Search 查看 AOSP 原始碼，因為實際使用時，原始碼會以相同方式顯示。詳情請參閱「開始使用 Code Search」。如要在 Android 程式碼搜尋中查看 main 分支中的所有程式碼，請前往 https://cs.android.com/android/platform/superproject/main。

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
   

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

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. 按一下程式碼擁有者，將他們加入審查。

   系統會啟用「SEND」按鈕。

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 Continuous Integration 資訊主頁，監控提交內容何時整合至樹狀結構。