提交补丁程序

本页介绍向 AOSP 提交补丁程序的完整流程，包括使用 Gerrit 查看和跟踪更改。

前提条件

  • 您需要先初始化编译环境、下载源代码、创建密码并按照密码生成器页面中的说明操作，然后再按照本页中的说明操作。

  • 如需详细了解 Repo 和 Git，请参阅开发部分。

  • 如需了解您可以在 Android 开放源代码社区中担任的不同角色，请参阅项目角色。

  • 如果您计划向 Android 平台贡献代码，请务必阅读 AOSP 的许可信息。

  • 请注意，如果要对 Android 使用的某些上游项目做出更改，请直接针对相应项目进行更改，如上游项目部分中所述。

贡献者须知

向服务器验证身份

您需要先创建一个密码（该密码将用于服务器识别您的身份），然后您才可以向 Gerrit 上传内容。请按照密码生成器页面上的说明操作。您只需执行此流程一次即可。如需了解详情，请参阅使用身份验证。

新建一个 Repo 分支

对于您打算进行的每项更改，请在相关的 Git 存储库中新建一个分支：

repo start NAME .

您可以在同一存储库中同时新建多个独立的分支。“NAME”分支是您的工作区的本地分支，不会包含在 Gerrit 或最终源代码树中。

进行更改

在您修改源代码文件（并且验证）后，请将这些更改提交到您的本地存储库：

git add -A
git commit -s

请在您的提交消息中提供相关更改的详细说明。该说明将会被推送到公开 AOSP 存储库，因此请按照我们的准则来撰写更改列表说明：

  • 以一行摘要（最多 50 个字符）开头，后跟一个空白行。这是 Git 和 Gerrit 支持的格式，适用于各种屏幕尺寸的设备。

  • 从第三行开始输入较长的说明，说明会在达到 72 个字符时自动硬回车换行。该部分应着重说明更改解决了什么问题，以及如何解决了问题。尽管我们建议您提供第二部分的内容，但这在实现新功能时是可选内容。

  • 添加对任何假设或背景信息的简短说明，这些内容可能对下一年研究此功能的其他贡献者起到很大的帮助作用。

以下是一个示例提交消息：

short description on first line

more detailed description of your patch,
which is likely to take up multiple lines.

repo init 期间提供的唯一更改 ID 以及您的姓名和电子邮件将自动添加到您的提交消息中。

上传到 Gerrit

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

repo upload

如果您在同一存储库中新建了多个分支，则系统会提示您选择要上传的分支。

上传成功后，Repo 会为您提供 Gerrit 上对应新页面的网址。访问该链接可在审核服务器上查看您上传的补丁程序、添加注释，或者为您的补丁程序申请特定审核者。

上传替换补丁程序

假设某位审核者已看过您的补丁程序，并要求您做一些小小的修改。您可以在 Git 中修改提交的内容，这会在 Gerrit 中生成一个新的补丁程序，该补丁程序与原始补丁程序具有相同的更改 ID。

git add -A
git commit --amend

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

解决同步冲突

如果提交到源代码树的其他补丁程序与您的存在冲突，那么您需要在源代码存储库的新 HEAD 的基础上对您的补丁程序执行“衍合”(rebase) 命令。执行此操作的一种简单方法是运行以下命令：

repo sync

此命令首先从源代码服务器获取更新，然后尝试在新的远程 HEAD 的基础上对您的 HEAD 自动执行衍合命令。

如果自动衍合命令失败，您就必须手动执行衍合。

repo rebase

使用 git mergetool 可帮助您处理衍合冲突。在成功合并冲突文件后，运行以下命令：

git rebase --continue

在自动或手动衍合完成之后，运行 repo upload 来提交衍合后的补丁程序。

提交内容获得批准后

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

审核者和验证者须知

审核更改

如果您被指定为某项更改的审批者，则需要确定以下事项：

  • 此项更改是否符合此项目既定的目的？

  • 此项更改在项目的现有架构中是否有效？

  • 此项更改是否会引入在将来造成问题的设计缺陷？

  • 此项更改是否遵循了针对此项目中制定的最佳做法？

  • 此项更改是否是执行所述功能的绝佳方式？

  • 此项更改是否会带来任何安全风险或不稳定性方面的风险？

如果您批准此项更改，请在 Gerrit 中将其标记为 LGTM（“看起来不错”）。

验证更改

如果您被指定为某项更改的验证者，则需要执行以下工作：

  • 使用其中一种下载命令将更改以补丁程序的形式添加到自己的本地客户端。

  • 编译和测试更改。

  • 在 Gerrit 中，使用“Publish Comments”（发布注释）功能将提交标记为“Verified”（已验证）或“Fails”（失败），并添加一条消息说明发现了哪些问题。

从 Gerrit 下载更改

已验证并合并的提交内容将在下一次运行 repo sync 时下载。如果您希望下载尚未获得批准的特定更改，请运行以下命令：

repo download TARGET CHANGE

其中 TARGET 是更改应该下载到的本地目录，CHANGE 是 Gerrit 中列出的更改编号。如需了解详细信息，请参阅 Repo 参考资料。

如何成为验证者或审批者？

简言之，为一个或多个 Android 项目贡献高质量代码。要详细了解 Android 开放源代码社区中的不同角色以及谁在担任这些角色，请参阅项目角色。

差异和注释

要在 Gerrit 中打开某项更改的详细信息，请点击该项更改的“ID 号”或“主题”。要比较已定版的原有代码与更新后的代码，请点击“Side-by-side diffs”（并排显示差异）下的文件名。

添加注释

社区中的任何人都可以使用 Gerrit 为提交的代码添加代码内注释。符合标准的注释会与 Gerrit 中其所依附的代码行或代码段相关。这可能是关于如何改进一行代码的简短而有建设性的建议，也可能是作者对于为什么这样编写代码的解释。

要添加代码内注释，请双击代码的相关行，然后在打开的文本框中编写注释。点击“Save”（保存）后，只有您可以看到自己的注释。

要发布注释以便让其他使用 Gerrit 的人可以看到，请点击“Publish Comments”（发布注释）按钮。您的注释将通过电子邮件发送给相应更改的所有相关方，包括更改的所有者、补丁程序集上传者（如果与所有者不同）以及所有当前审核者。

上游项目

Android 使用了许多其他开放源代码项目，例如代码行、分支和版本中所述的 Linux 内核和 WebKit。对于 external/ 下的大多数项目，如果要提交更改，则应该在上游进行，然后 Android 维护者会收到有关包含这些更改的新上游版本的通知。上传补丁程序也可能有助于我们跟踪新的上游版本，但如果是 Android 中广泛使用的项目（如下面提到的大多数大型项目），我们将很难做出更改。在这种情况下，我们倾向于在每次发布版本时进行升级。

一个有趣的特殊情况是 Bionic。由于大部分代码都是来自 BSD，因此，除非更改涉及对 Bionic 新内容的编码，否则我们宁愿使用上游修复程序，然后从相应的 BSD 中提取一个全新文件。（可惜的是，我们目前有各种不同的 BSD，但我们希望将来能够解决该问题，并能够更密切地跟踪上游项目。）

ICU4C

对于 external/icu4c 中的 ICU4C 项目，所有更改都应通过 icu-project.org/ 在上游进行。如需了解详情，请参阅提交 ICU 错误和功能请求。

LLVM/Clang/Compiler-rt

对于与 LLVM 相关的项目（external/clang、external/compiler-rt、external/llvm），所有更改都应通过 llvm.org/ 在上游进行。

mksh

对于 external/mksh 中的 MirBSD Korn Shell 项目，所有更改都应在上游进行：通过向 miros-mksh@mirbsd.org 发送电子邮件（无需订阅即可提交），或者在 Launchpad 中进行（可选）。

OpenSSL

对于 external/openssl 中的 OpenSSL 项目，所有更改都应通过 openssl.org 在上游进行。

V8

对于 external/v8 中的 V8 项目，所有更改都应通过 code.google.com/p/v8 在上游提交。如需了解详情，请参阅为 V8 贡献代码。

WebKit

对于 external/webkit 中的 WebKit 项目，所有更改都应通过 webkit.org 在上游进行。该过程需从提交 WebKit 错误开始。只有当该错误仅限于 Android 时，才可以在 Platform 和 OS 字段中使用 Android。如果附有建议的修复程序并包含测试结果，则错误更有可能引起审核者的注意。如需了解详情，请参阅为 WebKit 贡献代码。

zlib

对于 external/zlib 中的 zlib 项目，所有更改都应通过 zlib.net 在上游进行。