提交程式碼變更

本頁面說明將程式碼變更提交至 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 程式碼搜尋功能。您可以使用 Android Code Search 查看 AOSP 原始碼，因為實際使用時，原始碼會以相同方式顯示。詳情請參閱「開始使用 Code Search」。如要查看 Android 程式碼搜尋中 main 分支版本的所有程式碼，請前往 https://cs.android.com/android/platform/superproject/main。

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

  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」(建議擁有者)：

    在 Gerrit 中建議擁有者連結

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

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

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

    系統會啟用「SEND」按鈕。

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

  4. (選用) 按一下「自動提交」旁邊的「+1」，系統就會在您收到核准後自動提交變更。如果您沒有按一下這個按鈕，Google 員工就必須為您提交變更。

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

程式碼擁有者會審查您的程式碼變更，並提供意見回饋，讓您解決或核准變更。

判斷變更狀態

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

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

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

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

圖 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 持續整合資訊主頁，監控提交項目何時整合至樹狀結構中。