鍍金池/ 教程/ Android/ 提交補丁
下載源碼
根據設備構建
Git 資源
構建系統
Android 平臺 64 位構建指導
初始化編譯環(huán)境
Android 源代碼
品牌指南
已知的問(wèn)題
Repo 命令手冊
構建內核
Bug 的生命周期
代碼主線(xiàn)、分支和版本
使用 Eclipse
提交補丁
下載與構建
參與
項目角色
補丁的生命周期
提交 Bugs
關(guān)于代碼風(fēng)格的指導
開(kāi)發(fā)
代碼名稱(chēng),標簽和版本號

提交補丁

這個(gè)頁(yè)面將描述提交補丁到 AOSP 的全過(guò)程,包括校驗和 Gerrit 追蹤更改。

前提條件

  • 在按照說(shuō)明學(xué)習本頁(yè)面內容之前,你需要初始化構建環(huán)境,下載源碼,創(chuàng )建密碼和按照密碼生成頁(yè)面的說(shuō)明學(xué)習。

  • 可以在 developing 章節查看 Repo 和 Git 的詳細信息。
  • 可以在 Project roles 章節查看你可以在開(kāi)源社區扮演的各種角色信息。
  • 如果你打算在 Android 平臺貢獻代碼,應該先閱讀 AOSP 的權限聲明信息。
  • 注意更改一些使用 Android 的上游項目,你應該給這個(gè)項目創(chuàng )建一個(gè)目錄,像 Upstream Projects 中所說(shuō)的目錄。

貢獻者

與服務(wù)器進(jìn)行身份驗證

在你上傳內容到 Gerrit 的時(shí)候,你需要創(chuàng )建一個(gè)與服務(wù)器認證的密碼。按照 password generator 頁(yè)面的說(shuō)明。你只要在第一次的使用的時(shí)候這樣做。查看 Using Authentication 補充說(shuō)明。

從一個(gè) Repo 分支開(kāi)始

在你有意向更改的地方,可以在相關(guān)聯(lián)的 git 庫中新建一個(gè)分支:

$ repo start NAME .

你可以在同一個(gè)庫同一時(shí)間新建幾個(gè)獨立的分支。這個(gè)分支的名字是在你本地的工作空間,不包含在 gerrit 或者最終的源碼分支樹(shù)中。

更改

一但你更改了源碼里面的文件(請驗證它們),在本地庫中 commit 這個(gè)改變:

$ git add -A
$ git commit -s

在 commit 的消息中,寫(xiě)上你更改信息的詳細描述。這個(gè)描述信息將會(huì ) push 到公共的 AOSP 庫,所以請按照我們的指導來(lái)寫(xiě)更改列表的描述信息:

  • 開(kāi)始是一行摘要(最多 60 字),接著(zhù)空一行。這樣的格式在 git 和 gerrit 中用于各種顯示。

      short description on first line
    
      more detailed description of your patch,
      which is likely to take up multiple lines.
  • 這個(gè)描述信息應該著(zhù)重說(shuō)明解決了什么問(wèn)題,怎么解決的。第二部分盡管是值得滿(mǎn)意的,但是實(shí)現新功能的時(shí)候還是比較隨意的。

  • 寫(xiě)入一些簡(jiǎn)短的假定或者背景信息,這些內容可能對明年致力于這個(gè)功能的奉獻者很重要。

在執行 repo init 后得到的獨特的 change ID,名稱(chēng)和郵箱將會(huì )自動(dòng)添加到你的 commit 信息中。

上傳到 gerrit

一旦 commit 你的更改到個(gè)人歷史,就可以上傳到 gerrit。

$ repo upload

如果你在同一個(gè)庫中選擇了多個(gè)分支,你將會(huì )得到提示,讓你選擇一個(gè)分支上傳。

上傳成功之后,repo 將會(huì )給你提供一個(gè) Gerrit 新頁(yè)面的 URL。預覽這個(gè)鏈接并在評審服務(wù)器上查看你的補丁,添加評論,或者給你的補丁請求特定的評審員。

上傳一個(gè)代替的補丁

假如一個(gè)評審員已經(jīng)看了你的補丁,并且要求你做一些小的更改。你可以通過(guò) git 修改 commit 信息,這樣將會(huì )在 gerrit 中生成一個(gè)新的補丁,但是使用的是原先那個(gè) change ID。

注意,如果你在上傳補丁之前添加了其他 commits,你將需要手動(dòng)移動(dòng)你的 git HEAD。

$ git add -A
$ git commit --amend

當你上傳了修改的補丁,它將在 gerrit 和本地 git 歷史中代替之前的。

解決同步?jīng)_突

如果提交到源碼中的其他補丁和你的有沖突,你將需要在源碼庫新 HEAD 的頂部 rebase(重新定義分支版本庫狀態(tài))你的補丁。一個(gè)簡(jiǎn)單的方法就是運行:

$ repo sync

這個(gè)命令將會(huì )從服務(wù)器先 fetches 最新的源碼,然后會(huì )試圖自動(dòng) rebase HEAD 到新的遠程 HEAD 上面。

如果自動(dòng) rebase 沒(méi)有成功,你必須手動(dòng)執行 rebase。

$ repo rebase

使用 git mergetool 可能幫助你處理 rebase 沖突。一旦你成功地合并沖突文件,

$ git rebase --continue

手動(dòng)或者自動(dòng) rebase 完成之后,運行 repo upload 來(lái)提交你 rebase 補丁。

提交被批準之后

提交的內容在通過(guò)檢查和驗證過(guò)程之后,Gerrit 會(huì )自動(dòng)的 merges 這個(gè)更改到公共的庫中。其他用戶(hù)可以運行 repo sync 來(lái) pull 這個(gè)更新到自己的本地。

檢查員和審核者

檢查一個(gè)更改

如果你被分配成這個(gè)更改內容的批準者,你需要決定接下來(lái)的內容:

  • 這個(gè)更改是不是符合項目一開(kāi)始的目的?
  • 這個(gè)更改是不是在現存的構造中有效?
  • 這個(gè)更改引入的設計缺陷是否會(huì )在將來(lái)出現問(wèn)題?
  • 這個(gè)更改是否遵循這個(gè)項目中已建立的最佳實(shí)踐?
  • 這個(gè)更改是執行描述方法的好方式?
  • 這個(gè)更改是否引入任何安全或不穩定的風(fēng)險?

如果你準許了這個(gè)改變,請在 Gerrit 中用 LGTM(Look Good to ME)標記它。

審核更改

如果你被分配成這個(gè)更改內容的審核者,你需要做接下來(lái)的內容:

  • 使用其中一種下載命令將這個(gè)更改 Patch 到自己的本地客戶(hù)端。
  • 構建和測試這個(gè)更改。
  • 在 Gerrit 中,使用發(fā)布評論的方式來(lái)標記這個(gè) commit,用“Verified”或者“Fails”,并且添加一個(gè)消息來(lái)解釋哪些問(wèn)題是經(jīng)過(guò)鑒定的。

從 Gerrit 下載更改的內容

已經(jīng)審核和合并之后的提交將會(huì )在下一次 repo sync 的時(shí)候被下載。如果你希望下載一個(gè)特定的沒(méi)有經(jīng)過(guò)檢驗的更改,執行:

$ repo download TARGET CHANGE

這個(gè) TARGET 就是你下載的更改將要放到本地目錄的位置,CHANGE 就是在 Gerrit 中的更改列表的數字。想要知道更多信息,請查看Repo reference。

怎么樣才能成為一個(gè)審核者或者檢驗者?

簡(jiǎn)單來(lái)說(shuō),需要對一個(gè)或者多個(gè) Android 項目貢獻高質(zhì)量代碼。想要了解更多關(guān)于 Android 開(kāi)源社區的不同角色和都有誰(shuí)參與的信息,可以查看 Project Roles。

Diffs 和評論

在 Gerrit 中點(diǎn)擊一個(gè)更改的 Id number 或者 Subject 可以打開(kāi)這個(gè)更改的詳細信息。想知道現有的代碼和更新的代碼之間的差異,可以點(diǎn)擊文件名下的 Side-by-side diffs。

添加評論

在開(kāi)源社區的任何一個(gè)人都可以使用 Gerrit 來(lái)給提交的源碼添加內聯(lián)的評論。一個(gè)好的評論將會(huì )關(guān)聯(lián)行或者部分在 Gerrit 中的附加代碼。這或許是關(guān)于如何改進(jìn)一行代碼,簡(jiǎn)短的或者建設性的意見(jiàn),或者,這個(gè)也許是為什么作者這樣寫(xiě)代碼就有意義的解釋。

想要添加內聯(lián)評論,雙擊代碼中相關(guān)聯(lián)的行,并且在下一個(gè)打開(kāi)的窗口寫(xiě)上你的評論。你點(diǎn)擊保存之后,只有你可以看到你的評論。

想要發(fā)布你的評論,讓其他 Gerrit 使用者看到評論,點(diǎn)擊 Publish Comments 按鈕。你的評論內容將會(huì )通過(guò) email 發(fā)送給這個(gè)更改的所有當事人,包括更改的擁有者,補丁更新者(如果和擁有者不是同一個(gè)人),還有所有當前的檢查者。

Upstream 項目

Android 使用很多其他開(kāi)源項目,比如,Linux 內核和 WebKit,像在 Codelines,Branches,Releases 中描述的那樣。在 external/ 下的大多數項目,更改應該被 upstream,然后 Android 維護者通知新的 upstream 版本將包括這些更改。讓我們跟蹤一個(gè)新的 upstream 版本,可能對上傳補丁有好處。但是如果這些項目被廣泛使用,像下面提到的大多數項目一樣,將很難做出改變,對于這樣的項目,我們傾向于每次發(fā)布版本都升級。

一個(gè)有趣的特殊情況是仿生(bionic)。很多代碼都是來(lái)源于 BSD,所以除非改變的是新的仿生代碼,我們寧愿看到一個(gè) upstream 修復,然后從 適當的 BSD 上 pull 一個(gè)完整的新的文件(很可悲的是我們同時(shí)有很多不同的 BSD,但是我們希望在未來(lái)解決這個(gè)問(wèn)題,并且進(jìn)入一個(gè)我們更密切跟蹤 upstream 的位置)。

ICU4C

external/icu4c 目錄下,ICU4C 項目的所有改變,都應該在 icu-project.org/ 里被 upstream。查看 Submitting ICU Bugs and Feature Requests 獲取更多信息。

LLVM/Clang/Compiler-rt

LLVM-related 項目(external/clang, external/compiler-rt, external/llvm)的所有更改都應該在 llvm.org/ upstream。

mksh

external/mksh 目錄下,MirBSD Korn Shell 項目的所有更改要么發(fā)送 email 到 mirbsd.org(不需要訂閱提交)域名下的 miros-mksh,要么是 Launchpad 來(lái)進(jìn)行 upstream。

OpenSSL

external/openssl 目錄下的 OpenSSL 項目的所有更改都應該在 openssl.org 中 upstream。

V8

external/v8 目錄下 V8 項目的所有更改都應該提交到 code.google.com/p/v8 中 upstream。進(jìn)入 Contributing to V8 查看詳情。

WebKit

external/webkit 目錄下 WebKit 項目的所有更改都應該在 webkit.org 中 upstream。這個(gè)過(guò)程首先是提出一個(gè) Webkit bug。這個(gè) bug 應該是使用 Android 平臺和系統,并且這個(gè) bug 僅僅是針對于 Android 的。當添加了修復提議并有測試,Bugs 將更容易引起檢查員的注意。查看 Contributing Code to WebKit 獲取更多信息。

zlib

external/zlib 目錄下 zlib 項目的所有更改狗應該在 zlib.net 中 upstream。

上一篇:下載源碼下一篇:參與