提交補丁

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

先決條件

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

資源

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

對於貢獻者

與服務器進行身份驗證

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

啟動回購分支

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

repo start NAME .

您可以在同一個存儲庫中同時啟動多個獨立的分支。分支NAME是您工作區的本地分支,不包含在 Gerrit 或最終源代碼樹中。

做出改變

修改源文件,並驗證您的更改。

使用以下命令將更改提交到本地存儲庫:

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.
要閱讀有關良好提交描述(帶有示例)的博客,請參閱 Chris Beams的如何編寫 Git 提交消息

上傳到 Gerrit

提交對個人歷史記錄的更改後,使用以下命令將其上傳到 Gerrit:

repo upload

如果您在同一個存儲庫中啟動了多個分支,系統會提示您選擇要上傳的分支。

成功上傳後,Repo 會為您提供Gerrit上新頁面的 URL。單擊 Repo 為您提供的鏈接以在審核服務器上查看您的補丁、添加評論或為您的補丁請求特定的審核者。

請求審查

將更改上傳到 Gerrit 後,補丁必須由相應的代碼所有者審核和批准。在OWNERS文件中找到代碼所有者。

要查找適當的代碼所有者並將他們添加為您的更改的審閱者,請按照以下步驟操作。

  1. 在 Gerrit UI 中選擇SUGGEST OWNERS鏈接以查看補丁中文件的代碼所有者列表。

    在 Gerrit 中建議所有者鏈接
    圖 1. Gerrit 中的建議所有者鏈接
  2. 從列表中添加代碼所有者作為補丁的審閱者。

要確定補丁中文件的狀態,請檢查補丁中文件旁邊的以下圖標。

  • (複選標記圖標):由代碼所有者批准
  • (十字圖標):未經代碼所有者批准
  • (時鐘圖標):等待代碼所有者批准
圖 2.帶有顯示代碼所有者批准狀態的圖標的文件示例

上傳替換補丁

假設審閱者查看了您的補丁並要求進行小修改。您可以在 Git 中修改您的提交,這會導致 Gerrit 上的新補丁與原始補丁具有相同的更改 ID。

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以提交你的 rebase 補丁。

提交被批准後

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

對於上游項目

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

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

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

安卓內核

更喜歡在上游進行所有更改。如需一般指導,請遵循Android 內核貢獻指南

重症監護室

ICU-TC 主頁上的external/icuicu4c/icu4j/文件夾)中對 ICU 項目進行所有更改。有關更多信息,請參閱提交 ICU 錯誤和功能請求

CLDR

ICU 中的大多數語言數據來自Unicode CLDR 項目。請使用CLDR 更改請求向上游提交所有請求並添加標籤“Android”。

LLVM/Clang/編譯器-rt

LLVM Compiler Infrastructure 頁面上對 LLVM 相關項目( external/clangexternal/compiler-rtexternal/llvm )進行所有更改。

mksh

external/mksh對 MirBSD Korn Shell 項目進行所有更改,方法是向mirbsd.org域上的miros-mksh發送電子郵件(無需訂閱即可提交)或在Launchpad

OpenSSL

OpenSSL 頁面external/openssl中對 OpenSSL 項目進行所有更改。

V8

V8 問題頁面external/v8中提交對 V8 項目的所有更改。有關詳細信息,請參閱對 V8 的貢獻

網絡套件

WebKit 頁面external/webkit中對 WebKit 項目進行所有更改。通過提交 WebKit 錯誤開始該過程。在錯誤中,僅當錯誤特定於 Android 時,才將Android用於平台操作系統字段。在添加建議的修復並包含測試後,錯誤更有可能得到審閱者的注意。有關詳細信息,請參閱為 WebKit 貢獻代碼

zlib

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