提交補丁

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

先決條件

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

資源

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

對於貢獻者

與服務器進行身份驗證

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

啟動 Repo 分支

對於您打算進行的每個更改,請在相關 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 中廣泛使用,則這些更改可能很難進行,就像下面提到的大多數較大的項目一樣,它們通常會隨著每個版本的更新而升級。

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

安卓內核

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

重症監護室4C

ICU-TC 主頁的external/icu4c對 ICU4C 項目進行所有更改。有關更多信息,請參閱提交 ICU 錯誤和功能請求

LLVM/Clang/編譯器-rt

LLVM 編譯器基礎結構頁面上對LLVM相關項目( external/clangexternal/compiler-rtexternal/llvm )進行所有更改。

mksh

通過向mirbsd.org域上的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 項目進行所有更改。