提交補丁

本頁介紹了向 Android 開源項目 (AOSP) 提交補丁的完整過程，包括如何請求審查和使用Gerrit跟踪您的更改。

先決條件

首先，確保您已完成以下操作：

資源

  • 有關 Repo 和 Git 的詳細信息，請參閱源代碼管理工具頁面。
  • 有關 Android 開源社區中不同角色的信息，請參閱項目角色頁面。
  • 有關向 Android 平台貢獻代碼的許可信息，請參閱許可頁面。

對於貢獻者

使用服務器進行身份驗證

如果您與其他用戶共享 IP 地址，即使是常規使用模式也可以觸發配額。例如，當許多用戶在短時間內從同一 IP 地址同步新客戶端時，就會發生這種情況。經過身份驗證的訪問對每個用戶使用單獨的配額，而不管 IP 地址如何。要閱讀有關激活經過身份驗證的訪問的信息，請參閱使用身份驗證。

開始回購分支

對於您打算進行的每個更改，在相關的 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.

Making your change

Modify the source files, and validate your changes.

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.

Uploading 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.

Requesting 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

Uploading 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

另一個處理 rebase 衝突的工具是git mergetool 。成功合併衝突文件後，運行此命令：

git rebase --continue

自動或手動 rebase 完成後，運行repo upload以提交你的 rebased 補丁。

提交被批准後

在提交通過審查和驗證過程後，Gerrit 會自動將更改合併到公共存儲庫中。其他用戶可以運行repo sync將更新拉入他們各自的本地客戶端。

對於上游項目

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

您還可以上傳補丁，使新的上游版本被跟踪。請注意，如果該項目在 Android 中廣泛使用，那麼這些更改可能很難進行，就像下面提到的大多數較大的項目一樣，它們通常會隨著每個版本的發布而升級。

一個有趣的特例是 Bionic。那裡的大部分代碼都來自 BSD，因此除非更改是對 Bionic 的新代碼，否則請進行上游修復，然後從適當的 BSD 中提取一個全新的文件。

安卓內核

在上游進行所有更改。對於一般指導，請遵循Android 內核貢獻指南和為 GKI 頁面開發內核代碼。

加護病房

在ICU-TC 主頁上對external/icu （ icu4c/和icu4j/文件夾）中的 ICU 項目進行所有更改。有關更多信息，請參閱提交 ICU 錯誤和功能請求。將標籤“android”添加到所有上游 Jira 請求。

CLDR

ICU 中的大部分語言數據來自Unicode CLDR 項目。根據Contributing to CLDR向上游提交所有請求，並添加標籤“android”。

LLVM/Clang/編譯器-rt

在LLVM Compiler Infrastructure 頁面上對 LLVM 相關項目（ external/clang 、 external/compiler-rt 、 external/llvm ）進行所有更改。

mksh

通過向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 錯誤來啟動該過程。在錯誤中，僅當錯誤特定於 Android 時，才將Android用於平台和操作系統字段。在添加了建議的修復並包含測試後，錯誤更有可能受到審閱者的注意。有關詳細信息，請參閱向 WebKit 貢獻代碼。

zlib

在zlib 主頁上的external/zlib對 zlib 項目進行所有更改。