提交程式碼變更

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

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

簽署貢獻者授權協議

為 AOSP 貢獻任何程式碼變更前，請務必先閱讀貢獻者授權協議和標頭，並簽署下列其中一項協議：

• 如果您是以個人提案者的身分提案，請簽署《Individual Contributor License Agreement》。
• 如果您是公司員工，請確認貴公司已簽署《公司貢獻者授權協議》，授權您代表公司做出貢獻。

建立分支版本

針對您打算進行的每項程式碼變更，執行下列步驟：

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 程式碼搜尋功能，查看實際使用 AOSP 時的原始碼版面配置。詳情請參閱「開始使用程式碼搜尋」。如要在 Android 程式碼搜尋中查看最新 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 決策背後的脈絡。平台 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

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

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

2. 先按 A 鍵再按 Enter 鍵。

   系統會提示你核准上傳：

   Upload project frameworks/native/ to remote branch android16-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 中變更的連結。按一下連結即可在審查伺服器上查看變更、新增註解，或為變更要求特定審查者。所有程式碼變更都必須由適當的程式碼擁有者審查。

如要申請複查，請按照下列步驟操作：

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

   

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

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

2. 按一下程式碼擁有者，將他們新增至審查。

   「傳送」按鈕已啟用。

3. (選用) 輸入其他人的電子郵件地址，請對方審查變更。

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

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

判斷變更狀態

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

• 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

提交變更

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

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