提交補丁

本頁描述了向 Android 開源專案 (AOSP) 提交補丁的完整過程,包括如何請求審核以及如何使用Gerrit追蹤您的變更。 Gerrit 是一個基於 Web 的程式碼審查系統,適用於使用 Git 的專案。 Gerrit 鼓勵更集中地使用 Git,允許所有授權使用者提交更改,如果透過程式碼審查,這些更改將自動合併。此外,Gerrit 使審查變得容易,在瀏覽器中並排顯示變更並啟用內聯註釋。

先決條件

首先,請確保您已完成以下操作:

資源

配置Git

要使用 Gerrit,您的電子郵件必須與註冊的 Google 帳戶關聯。執行以下命令,使用與註冊的 Google 帳戶關聯的名稱和電子郵件地址設定 Git:

git config --global user.name Your Name
git config --global user.email your_email@gmail.com
    

與伺服器進行身份驗證

如果您與其他使用者共用 IP 位址,即使對於常規使用模式也可能會觸發配額。例如,當許多使用者在短時間內從相同 IP 位址同步新用戶端時,就會發生這種情況。無論 IP 位址為何,經過驗證的存取都會為每個使用者使用單獨的配額。要了解有關啟動經過身份驗證的存取的信息,請參閱使用身份驗證

啟動一個 Repo 分支

對於您打算進行的每項更改,請在相關 Git 儲存庫中啟動一個新分支:

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

git add -A
git commit -s

更改說明

  • 第 1 行:標題

    提供一行摘要(最多50 個字元)

    Git 和 Gerrit 使用此格式進行各種顯示。這是提交訊息中最重要、最密集的部分。考慮使用前綴來描述您更改的區域,後跟您在此提交中所做更改的描述,例如以ui作為前綴的這個:

    ui: Removes deprecated widget

  • 第 2 行:空白

    始終將此行保留為空白。

  • 第 3 行:主體

    從這一行開始寫一個較長的描述。

    此內容必須硬包裝,最多 72 個字元。描述變更解決了什麼問題以及如何解決。儘管在實現新功能時這是可選的,但如果其他人以後引用此更改,這對他們非常有幫助,尤其是對於調試而言。

    簡要說明當其他貢獻者處理此功能時可能很重要的任何假設或背景資訊。

repo init期間提供的唯一更改 ID 以及您的姓名和電子郵件會自動添加到您的提交訊息中。

這是一個提交訊息範例:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit
  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original.

git add -A
git commit --amend

當您上傳修改後的補丁時,它會取代 Gerrit 上和本地 Git 歷史記錄中的原始補丁。

解決同步衝突

如果提交到來源樹的其他補丁與您的補丁衝突,請在來源儲存庫的新HEAD之上重新調整您的補丁。為此,請執行以下命令:

repo sync

repo sync命令從來源伺服器取得更新,然後嘗試自動將您的HEAD重新設定為新的遠端HEAD

如果自動變基不成功,請執行手動變基。

repo rebase

另一個處理變基衝突的工具是git mergetool 。成功合併衝突檔案後,執行以下命令:

git rebase --continue

自動或手動變基完成後,執行repo upload以提交變基補丁。

提交獲得批准後

提交通過審查和驗證流程後,Gerrit 會自動將變更合併到公共儲存庫中。其他使用者可以執行repo sync將更新拉取到各自的本機用戶端。

對於上游項目

Android 使用許多其他開源項目,例如 Linux 核心和 WebKit,如Android 軟體管理中所述。對於大多數駐留在external/下的項目,請在上游進行更改,然後通知 Android 維護人員包含您的更改的新上游版本。

您也可以上傳導致新上游版本被追蹤的補丁。請注意,如果該專案在 Android 中廣泛使用,那麼做出這些變更可能會很困難,就像下面提到的大多數較大的專案一樣,這些專案通常會隨著每個版本的發布而升級。

一個有趣的特例是 Bionic。其中大部分程式碼來自 BSD,因此除非更改是針對 Bionic 的新程式碼,否則請進行上游修復,然後從對應的 BSD 中提取全新檔案。

安卓內核

在上游進行所有更改。如需一般指導,請遵循Android 核心貢獻指南Develop Kernel Code for GKI頁面。

重症監護室

ICU-TC 主頁上的external/icuicu4c/icu4j/資料夾)中的 ICU 項目進行所有更改。有關更多信息,請參閱提交 ICU 錯誤和功能請求。將標籤“android”添加到所有上游 Jira 請求。

CLDR

ICU 中的大多數語言資料都來自Unicode CLDR 專案。根據Contributing to CLDR向上游提交所有請求,並新增標籤「android」。

LLVM/Clang/編譯器-rt

LLVM 編譯器基礎架構頁面上對 LLVM 相關專案( external/clangexternal/compiler-rtexternal/llvm )進行所有變更。

姆克什

透過向mirbsd.org網域上的miros-mksh (無需在那裡提交訂閱)或在Launchpad發送電子郵件,對external/mksh上的 MirBSD Korn Shell 專案進行所有更改。

開放式SSL

OpenSSL 頁面上的external/openssl中的 OpenSSL 專案進行所有變更。

V8

V8 問題頁面上的external/v8提交對 V8 專案的所有變更。有關詳細信息,請參閱為 V8 做出貢獻

網路工具包

WebKit 頁面external/webkit中對 WebKit 專案進行所有變更。透過提交 WebKit bug來啟動該流程。在錯誤中,僅當錯誤特定於 Android 時,才會使用Android作為平台作業系統欄位。在添加建議的修復程序並包含測試後,錯誤更有可能引起審閱者的注意。有關詳細信息,請參閱向 WebKit 貢獻代碼

茲庫

zlib 主頁上的external/zlib中的 zlib 專案進行所有變更。

,

本頁描述了向 Android 開源專案 (AOSP) 提交補丁的完整過程,包括如何請求審核以及如何使用Gerrit追蹤您的變更。 Gerrit 是一個基於 Web 的程式碼審查系統,適用於使用 Git 的專案。 Gerrit 鼓勵更集中地使用 Git,允許所有授權使用者提交更改,如果透過程式碼審查,這些更改將自動合併。此外,Gerrit 使審查變得容易,在瀏覽器中並排顯示變更並啟用內聯註釋。

先決條件

首先,請確保您已完成以下操作:

資源

配置Git

要使用 Gerrit,您的電子郵件必須與註冊的 Google 帳戶關聯。執行以下命令,使用與註冊的 Google 帳戶關聯的名稱和電子郵件地址設定 Git:

git config --global user.name Your Name
git config --global user.email your_email@gmail.com
    

與伺服器進行身份驗證

如果您與其他使用者共用 IP 位址,即使對於常規使用模式也可能會觸發配額。例如,當許多使用者在短時間內從相同 IP 位址同步新用戶端時,就會發生這種情況。無論 IP 位址為何,經過驗證的存取都會為每個使用者使用單獨的配額。要了解有關啟動經過身份驗證的存取的信息,請參閱使用身份驗證

啟動一個 Repo 分支

對於您打算進行的每項更改,請在相關 Git 儲存庫中啟動一個新分支:

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

git add -A
git commit -s

更改說明

  • 第 1 行:標題

    提供一行摘要(最多50 個字元)

    Git 和 Gerrit 使用此格式進行各種顯示。這是提交訊息中最重要、最密集的部分。考慮使用前綴來描述您更改的區域,後跟您在此提交中所做更改的描述,例如以ui作為前綴的這個:

    ui: Removes deprecated widget

  • 第 2 行:空白

    始終將此行保留為空白。

  • 第 3 行:主體

    從這一行開始寫一個較長的描述。

    此內容必須硬包裝,最多 72 個字元。描述變更解決了什麼問題以及如何解決。儘管在實現新功能時這是可選的,但如果其他人以後引用此更改,這對他們非常有幫助,尤其是對於調試而言。

    簡要說明當其他貢獻者處理此功能時可能很重要的任何假設或背景資訊。

repo init期間提供的唯一更改 ID 以及您的姓名和電子郵件會自動添加到您的提交訊息中。

這是一個提交訊息範例:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit
  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original.

git add -A
git commit --amend

當您上傳修改後的補丁時,它會取代 Gerrit 上和本地 Git 歷史記錄中的原始補丁。

解決同步衝突

如果提交到來源樹的其他補丁與您的補丁衝突,請在來源儲存庫的新HEAD之上重新調整您的補丁。為此,請執行以下命令:

repo sync

repo sync命令從來源伺服器取得更新,然後嘗試自動將您的HEAD重新設定為新的遠端HEAD

如果自動變基不成功,請執行手動變基。

repo rebase

另一個處理變基衝突的工具是git mergetool 。成功合併衝突檔案後,執行以下命令:

git rebase --continue

自動或手動變基完成後,執行repo upload以提交變基補丁。

提交獲得批准後

提交通過審查和驗證流程後,Gerrit 會自動將變更合併到公共儲存庫中。其他使用者可以執行repo sync將更新拉取到各自的本機用戶端。

對於上游項目

Android 使用許多其他開源項目,例如 Linux 核心和 WebKit,如Android 軟體管理中所述。對於大多數駐留在external/下的項目,請在上游進行更改,然後通知 Android 維護人員包含您的更改的新上游版本。

您也可以上傳導致新上游版本被追蹤的補丁。請注意,如果該專案在 Android 中廣泛使用,那麼做出這些變更可能會很困難,就像下面提到的大多數較大的專案一樣,這些專案通常會隨著每個版本的發布而升級。

一個有趣的特例是 Bionic。其中大部分程式碼來自 BSD,因此除非更改是針對 Bionic 的新程式碼,否則請進行上游修復,然後從對應的 BSD 中提取全新檔案。

安卓內核

在上游進行所有更改。如需一般指導,請遵循Android 核心貢獻指南Develop Kernel Code for GKI頁面。

重症監護室

ICU-TC 主頁上的external/icuicu4c/icu4j/資料夾)中的 ICU 項目進行所有更改。有關更多信息,請參閱提交 ICU 錯誤和功能請求。將標籤“android”添加到所有上游 Jira 請求。

CLDR

ICU 中的大多數語言資料都來自Unicode CLDR 專案。根據Contributing to CLDR向上游提交所有請求,並新增標籤「android」。

LLVM/Clang/編譯器-rt

LLVM 編譯器基礎架構頁面上對 LLVM 相關專案( external/clangexternal/compiler-rtexternal/llvm )進行所有變更。

姆克什

透過向mirbsd.org網域上的miros-mksh (無需在那裡提交訂閱)或在Launchpad發送電子郵件,對external/mksh上的 MirBSD Korn Shell 專案進行所有更改。

開放式SSL

OpenSSL 頁面上的external/openssl中的 OpenSSL 專案進行所有變更。

V8

V8 問題頁面上的external/v8提交對 V8 專案的所有變更。有關詳細信息,請參閱為 V8 做出貢獻

網路工具包

WebKit 頁面external/webkit中對 WebKit 專案進行所有變更。透過提交 WebKit bug來啟動該流程。在錯誤中,僅當錯誤特定於 Android 時,才會使用Android作為平台作業系統欄位。在添加建議的修復程序並包含測試後,錯誤更有可能引起審閱者的注意。有關詳細信息,請參閱向 WebKit 貢獻代碼

茲庫

zlib 主頁上的external/zlib中的 zlib 專案進行所有變更。