提交补丁

本页面介绍了向 Android 开源项目 (AOSP) 提交补丁的全过程，包括如何使用 Gerrit 来请求审核以及跟踪您所做的更改。 Gerrit 是一个基于网页的代码审核系统，适用于使用 Git 的项目。Gerrit 允许所有授权用户提交更改（这些更改通过代码审核后会自动纳入到项目中），以此鼓励他们更集中地使用 Git。此外，Gerrit 会在浏览器中并排显示更改，并支持代码内注释，从而使审核工作变得非常轻松。

前提条件

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

资源

  • 如需详细了解 Repo 和 Git，请参阅源代码控制工具页面。
  • 如需了解 Android 开源社区中的不同角色，请参阅项目角色页面。
  • 如需了解向 Android 平台贡献代码时如何进行许可，请参阅许可页面。

配置 Git

若要使用 Gerrit，您的电子邮件地址必须与已注册的 Google 账号相关联。运行以下命令，可使用与已注册的 Google 账号关联的名称和电子邮件地址来配置 Git：

git config --global user.name Your Name
git config --global user.email your_email@gmail.com

向服务器验证身份

如果您与其他用户共用一个 IP 地址，即使在常规使用模式下也可能触发配额。例如，当许多用户在短时间内从同一个 IP 地址同步新客户端时，就可能发生这种情况。不论 IP 地址是什么，需验证身份的访问方式都会为每位用户使用单独的配额。如需了解如何激活需身份验证的访问，请参阅使用身份验证部分。

新建一个 Repo 分支

在您打算进行的每项更改中，在相关 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.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

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.

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

Request 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

Upload 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 的顶部对补丁执行 rebase 操作。为此，请运行以下命令： 

repo sync

repo sync 命令会从源服务器获取更新，然后尝试自动将您的 HEAD rebase 到新的远程 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 项目的所有更改。