提交补丁

本页面介绍了向 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 的博文 How to Write a Git Commit Message（如何撰写 Git 提交消息）。

上传到 Gerrit

在将更改提交到个人历史记录后，可以使用以下命令将更改上传到 Gerrit： 

repo upload

如果您在同一仓库中启动了多个分支，系统会提示您选择要上传的分支。

上传成功后，Repo 会向您提供 Gerrit 上新页面的网址。点击 Repo 提供的链接后，您可在审核服务器上查看您上传的补丁、添加注释，或者申请由特定审核者来审核您的补丁。

申请审核

将更改上传到 Gerrit 之后，补丁必须由相应的代码所有者审核和批准。代码所有者信息位于 OWNERS 文件中。

如需查找相应的代码所有者并将其添加为更改的审核者，请按以下步骤操作。

  1. 在 Gerrit 界面中选择 SUGGEST OWNERS 链接，以查看您的补丁中文件的代码所有者列表。

    Gerrit 中的“SUGGEST OWNERS”链接
    图 1. Gerrit 中的“SUGGEST OWNERS”链接

  2. 将列表中的代码所有者添加为您的补丁的审核者。

如需确定您的补丁中文件的状态，请查看补丁中文件旁边的以下图标。

  • （对勾标记图标）：已经过代码所有者批准
  • （叉号图标）：未经过代码所有者批准
  • （时钟图标）：正等待代码所有者审批
图 2. 一个带有显示代码所有者审批状态图标的文件示例

上传替换补丁

假设某位审核者已看过您的补丁，并要求您做一些小小的修改。您可以在 Git 中修改提交内容，此操作会在 Gerrit 上创建一个新补丁，其更改 ID 与原始更改 ID 相同。 

git add -A
git commit --amend

当您上传修改后的补丁时，它会替换 Gerrit 上和您本地 Git 历史记录中的原始补丁。

解决同步冲突

如果其他补丁提交到了与您的源代码树冲突的源代码树，您需要在源代码库的新 HEAD 的顶部对补丁执行 rebase 操作。为此，请运行以下命令： 

repo sync

repo sync命令会从源服务器获取更新，然后尝试自动将您的 HEAD 到新的远程 HEAD 上。

如果自动 rebase 操作不成功，请执行手动 rebase 操作。

repo rebase

另一个可用于处理 rebase 冲突的工具是 git mergetool。成功合并冲突的文件后，请运行以下命令： 

git rebase --continue

自动或手动 rebase 完成后，请运行 repo upload 提交 rebase 后的补丁。

提交内容获得批准后

在提交内容通过审核和验证流程之后，Gerrit 会自动将更改合并到公开仓库。其他用户可以运行 repo sync 将更新提取到他们各自的本地客户端。

上游项目

Android 会使用许多其他开源项目（例如 Linux 内核和 WebKit），如 Android 软件管理中所述。对于 external/ 下的大多数项目，请在上游进行更改，然后将包含这些更改的新上游版本告知 Android 维护人员。

您还可以上传补丁，以跟踪新的上游版本。请注意，如果是 Android 中广泛使用的项目（如下面提到的大多数大型项目），我们将很难做出更改；这类项目通常会在每次发布版本时进行升级。

一个有趣的特殊情况是 Bionic。因为大部分代码都是来自 BSD，所以除非对 Bionic 的新代码进行更改，否则请进行上游修复，然后从适当的 BSD 提取全新文件。

Android 内核

在上游进行所有更改。如需获得一般性指导，请参阅 Android 内核贡献准则和为 GKI 开发内核代码页面。

ICU

在 ICU-TC 首页上的 external/icu（icu4c/ 和 icu4j/ 文件夹）进行对 ICU 项目的所有更改。如需了解详情，请参阅提交 ICU bug 和功能请求。向所有上游 Jira 请求添加标签“android”。

CLDR

ICU 中的大多数语言数据都来自 Unicode CLDR 项目。根据为 CLDR 贡献代码向上游提交所有请求，并添加标签“android”。

LLVM/Clang/Compiler-rt

在 LLVM 编译程序基础架构页上，对与 LLVM 相关的项目（external/clang、external/compiler-rt、external/llvm）进行所有更改。

mksh

在 external/mksh 对 MirBSD Korn Shell 项目进行所有更改，方式是发送电子邮件到 mirbsd.org 网域上的 miros-mksh（无需订阅即可提交），或在 Launchpad 进行。

OpenSSL

在 OpenSSL 页面上的 external/openssl 进行对 OpenSSL 项目的所有更改。

V8

在 V8 问题页面上的 external/v8 提交对 V8 项目的所有更改。如需了解详情，请参阅为 V8 贡献代码。

WebKit

在 WebKit 页面 的 external/webkit 进行对 WebKit 项目的所有更改。通过提交 WebKit bug 启动该过程。在 bug 中，如果 bug 是针对 Android 的，请在 Platform 和 OS 字段中使用 Android。添加建议的修复程序并纳入测试结果后，bug 更有可能引起审核者的注意。如需了解详情，请参阅为 WebKit 贡献代码。

zlib

在 zlib 首页上的 external/zlib 进行对 zlib 项目的所有更改。