zh-cn/setup/submit-patches.html - platform/docs/source.android.com - Git at Google

 <html devsite><head>
     <title>提交补丁程序</title>
     <meta name="project_path" value="/_project.yaml"/>
     <meta name="book_path" value="/_book.yaml"/>
   </head>
   <body>
   <!--
       Copyright 2017 The Android Open Source Project

       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at

           http://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.
   -->

 <p>本页介绍向 AOSP 提交补丁程序的完整流程，包括使用 <a href="https://android-review.googlesource.com/">Gerrit</a> 查看和跟踪更改。</p>
 <h3 id="prerequisites">前提条件</h3>
 <ul>
 <li>
 <p>您需要先<a href="/setup/initializing.html">初始化编译环境</a>、<a href="/setup/downloading.html">下载源代码</a>、<a href="https://android.googlesource.com/new-password">创建密码</a>并按照密码生成器页面中的说明操作，然后再按照本页中的说明操作。</p>
 </li>
 <li>
 <p>如需详细了解 Repo 和 Git，请参阅<a href="/setup/developing.html">开发</a>部分。</p>
 </li>
 <li>
 <p>如需了解您可以在 Android 开源社区中担任的不同角色，请参阅<a href="/setup/roles.html">项目角色</a>。</p>
 </li>
 <li>
 <p>如果您计划向 Android 平台贡献代码，请务必阅读 <a href="/setup/licenses.html">AOSP 的许可信息</a>。</p>
 </li>
 <li>
 <p>请注意，如果要对 Android 使用的某些上游项目做出更改，请直接针对相应项目进行更改，如<a href="#upstream-projects">上游项目</a>部分中所述。</p>
 </li>
 </ul>

 <h2 id="for-contributors">贡献者须知</h2>

 <h3 id="authenticate-with-the-server">向服务器验证身份</h3>
 <p>您需要先<a href="https://android.googlesource.com/new-password">创建一个密码</a>（该密码将用于服务器识别您的身份），然后您才可以向 Gerrit 上传内容。请按照密码生成器页面上的说明操作。您只需执行此流程一次即可。如需了解更多详情，请参阅<a href="/setup/downloading.html#using-authentication">使用身份验证</a>。</p>
 <h3 id="start-a-repo-branch">新建一个 Repo 分支</h3>
 <p>对于您打算进行的每项更改，请在相关的 Git 存储库中新建一个分支：</p>
 <pre class="devsite-terminal devsite-click-to-copy">
 repo start <var>NAME</var> .
 </pre>
 <p>您可以在同一存储库中同时新建多个独立的分支。“NAME”分支是您的工作区的本地分支，不会包含在 Gerrit 或最终源代码树中。</p>
 <h3 id="make-your-change">进行更改</h3>
 <p>在您修改源代码文件（并且验证）后，请将这些更改提交到您的本地存储库：</p>
 <pre class="devsite-click-to-copy">
 <code class="devsite-terminal">git add -A</code>
 <code class="devsite-terminal">git commit -s</code>
 </pre>
 <p>请在您的提交消息中提供相关更改的详细说明。该说明将会被推送到公开 AOSP 存储库，因此请按照我们的准则来撰写更改列表说明：</p>
 <ul>

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

 <li>
 <p>从第三行开始输入较长的说明，说明会在达到 72 个字符时自动硬回车换行。该部分应着重说明更改解决了什么问题，以及如何解决了问题。尽管我们建议您提供第二部分的内容，但这在实现新功能时是可选内容。</p>
 </li>
 <li>
 <p>添加对任何假设或背景信息的简短说明，这些内容可能对下一年研究此功能的其他贡献者起到很大的帮助作用。</p>
 </li>
 </ul>

 <p>以下是一个示例提交消息：</p>
 <pre class="devsite-click-to-copy">short description on first line

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

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

 <h3 id="upload-to-gerrit">上传到 Gerrit</h3>
 <p>将更改提交到您的个人历史记录后，请使用以下命令将其上传到 Gerrit：</p>
 <pre class="devsite-terminal devsite-click-to-copy">
 repo upload
 </pre>
 <p>如果您在同一存储库中新建了多个分支，则系统会提示您选择要上传的分支。</p>
 <p>上传成功后，Repo 会为您提供 <a href="https://android-review.googlesource.com/">Gerrit</a> 上对应新页面的网址。访问该链接可在审核服务器上查看您上传的补丁程序、添加注释，或者为您的补丁程序申请特定审核者。</p>
 <h3 id="uploading-a-replacement-patch">上传替换补丁程序</h3>
 <p>假设某位审核者已看过您的补丁程序，并要求您做一些小小的修改。您可以在 Git 中修改提交的内容，这会在 Gerrit 中生成一个新的补丁程序，该补丁程序与原始补丁程序具有相同的更改 ID。</p>
 <aside class="note"><b>注意</b>：如果您在上传该补丁程序之后进行了其他提交，那么您将需要手动移动 Git HEAD。</aside>
 <pre class="devsite-click-to-copy">
 <code class="devsite-terminal">git add -A</code>
 <code class="devsite-terminal">git commit --amend</code>
 </pre>
 <p>当您上传修改后的补丁程序时，它将替换 Gerrit 和本地 Git 历史记录中的原始补丁程序。</p>

 <h3 id="resolving-sync-conflicts">解决同步冲突</h3>
 <p>如果提交到源代码树的其他补丁程序与您的存在冲突，那么您需要在源代码存储库的新 HEAD 的基础上对您的补丁程序执行“衍合”(rebase) 命令。执行此操作的一种简单方法是运行以下命令：</p>
 <pre class="devsite-terminal devsite-click-to-copy">
 repo sync
 </pre>
 <p>此命令首先从源代码服务器获取更新，然后尝试在新的远程 HEAD 的基础上对您的 HEAD 自动执行衍合命令。</p>
 <p>如果自动衍合命令失败，您就必须手动执行衍合。</p>
 <pre class="devsite-terminal devsite-click-to-copy">
 repo rebase
 </pre>
 <p>使用 <code>git mergetool</code> 可帮助您处理衍合冲突。在成功合并冲突文件后，运行以下命令：</p>
 <pre class="devsite-terminal devsite-click-to-copy">
 git rebase --continue
 </pre>
 <p>在自动或手动衍合完成之后，运行 <code>repo
 upload</code> 来提交衍合后的补丁程序。</p>

 <h3 id="after-a-submission-is-approved">提交内容获得批准后</h3>
 <p>在提交内容通过审核和验证流程之后，Gerrit 会自动将更改合并到公开存储库。其他用户可以运行 <code>repo sync</code> 将更新提取到自己的本地客户端。</p>

 <h2 id="upstream-projects">上游项目</h2>
 <p>Android 使用了许多其他开源项目，例如<a href="/setup/code-lines.html">代码流水线、分支和版本</a>中所述的 Linux 内核和 WebKit。对于 <code>external/</code> 下的大多数项目，如果要提交更改，则应该在上游进行，然后 Android 维护者会收到有关包含这些更改的新上游版本的通知。上传补丁程序也可能有助于我们跟踪新的上游版本，但如果是 Android 中广泛使用的项目（如下面提到的大多数大型项目），我们将很难做出更改。在这种情况下，我们倾向于在每次发布版本时进行升级。</p>
 <p>一个有趣的特殊情况是 Bionic。由于大部分代码都是来自 BSD，因此，除非更改涉及对 Bionic 新内容的编码，否则我们宁愿使用上游修复程序，然后从相应的 BSD 中提取一个全新文件。（可惜的是，我们目前有各种不同的 BSD，但我们希望将来能够解决该问题，并能够更密切地跟踪上游项目。）</p>
 <h3 id="icu4c">ICU4C</h3>
 <p>对于 <code>external/icu4c</code> 中的 ICU4C 项目，所有更改都应通过 <a href="http://site.icu-project.org/">icu-project.org/</a> 在上游进行。
 如需了解详情，请参阅<a href="http://site.icu-project.org/bugs">提交 ICU 错误和功能请求</a>。</p>

 <h3 id="llvmclangcompiler-rt">LLVM/Clang/Compiler-rt</h3>
 <p>对于与 LLVM 相关的项目（<code>external/clang</code>、<code>external/compiler-rt</code>、<code>external/llvm</code>），所有更改都应通过 <a href="http://llvm.org/">llvm.org/</a> 在上游进行。</p>

 <h3 id="mksh">mksh</h3>
 <p>对于 <code>external/mksh</code> 中的 MirBSD Korn Shell 项目，所有更改都应在上游进行：通过向 [email protected] 发送电子邮件（无需订阅即可提交），或者在 <a href="https://launchpad.net/mksh">Launchpad</a> 中进行（可选）。
 </p>
 <h3 id="openssl">OpenSSL</h3>
 <p>对于 <code>external/openssl</code> 中的 OpenSSL 项目，所有更改都应通过 <a href="http://www.openssl.org">openssl.org</a> 在上游进行。</p>
 <h3 id="v8">V8</h3>
 <p>对于 <code>external/v8</code> 中的 V8 项目，所有更改都应通过 <a href="https://code.google.com/p/v8">code.google.com/p/v8</a> 在上游提交。如需了解详情，请参阅<a href="https://code.google.com/p/v8/wiki/Contributing">为 V8 贡献代码</a>。</p>
 <h3 id="webkit">WebKit</h3>
 <p>对于 <code>external/webkit</code> 中的 WebKit 项目，所有更改都应通过 <a href="http://www.webkit.org">webkit.org</a> 在上游进行。该过程需从提交 WebKit 错误开始。
 只有当该错误仅限于 Android 时，才可以在 <code>Platform</code> 和 <code>OS</code> 字段中使用 <code>Android</code>。如果附有建议的修复程序并包含测试结果，则错误更有可能引起审核者的注意。如需了解详情，请参阅<a href="http://webkit.org/coding/contributing.html">为 WebKit 贡献代码</a>。</p>
 <h3 id="zlib">zlib</h3>
 <p>对于 <code>external/zlib</code> 中的 zlib 项目，所有更改都应通过 <a href="http://zlib.net">zlib.net</a> 在上游进行。</p>

 </body></html>
	<html devsite><head>
	<title>提交补丁程序</title>
	<meta name="project_path" value="/_project.yaml"/>
	<meta name="book_path" value="/_book.yaml"/>
	</head>
	<body>
	<!--
	Copyright 2017 The Android Open Source Project

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<p>本页介绍向 AOSP 提交补丁程序的完整流程，包括使用 <a href="https://android-review.googlesource.com/">Gerrit</a> 查看和跟踪更改。</p>
	<h3 id="prerequisites">前提条件</h3>
	<ul>
	<li>
	<p>您需要先<a href="/setup/initializing.html">初始化编译环境</a>、<a href="/setup/downloading.html">下载源代码</a>、<a href="https://android.googlesource.com/new-password">创建密码</a>并按照密码生成器页面中的说明操作，然后再按照本页中的说明操作。</p>
	</li>
	<li>
	<p>如需详细了解 Repo 和 Git，请参阅<a href="/setup/developing.html">开发</a>部分。</p>
	</li>
	<li>
	<p>如需了解您可以在 Android 开源社区中担任的不同角色，请参阅<a href="/setup/roles.html">项目角色</a>。</p>
	</li>
	<li>
	<p>如果您计划向 Android 平台贡献代码，请务必阅读 <a href="/setup/licenses.html">AOSP 的许可信息</a>。</p>
	</li>
	<li>
	<p>请注意，如果要对 Android 使用的某些上游项目做出更改，请直接针对相应项目进行更改，如<a href="#upstream-projects">上游项目</a>部分中所述。</p>
	</li>
	</ul>

	<h2 id="for-contributors">贡献者须知</h2>

	<h3 id="authenticate-with-the-server">向服务器验证身份</h3>
	<p>您需要先<a href="https://android.googlesource.com/new-password">创建一个密码</a>（该密码将用于服务器识别您的身份），然后您才可以向 Gerrit 上传内容。请按照密码生成器页面上的说明操作。您只需执行此流程一次即可。如需了解更多详情，请参阅<a href="/setup/downloading.html#using-authentication">使用身份验证</a>。</p>
	<h3 id="start-a-repo-branch">新建一个 Repo 分支</h3>
	<p>对于您打算进行的每项更改，请在相关的 Git 存储库中新建一个分支：</p>
	<pre class="devsite-terminal devsite-click-to-copy">
	repo start <var>NAME</var> .
	</pre>
	<p>您可以在同一存储库中同时新建多个独立的分支。“NAME”分支是您的工作区的本地分支，不会包含在 Gerrit 或最终源代码树中。</p>
	<h3 id="make-your-change">进行更改</h3>
	<p>在您修改源代码文件（并且验证）后，请将这些更改提交到您的本地存储库：</p>
	<pre class="devsite-click-to-copy">
	<code class="devsite-terminal">git add -A</code>
	<code class="devsite-terminal">git commit -s</code>
	</pre>
	<p>请在您的提交消息中提供相关更改的详细说明。该说明将会被推送到公开 AOSP 存储库，因此请按照我们的准则来撰写更改列表说明：</p>
	<ul>

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

	<li>
	<p>从第三行开始输入较长的说明，说明会在达到 72 个字符时自动硬回车换行。该部分应着重说明更改解决了什么问题，以及如何解决了问题。尽管我们建议您提供第二部分的内容，但这在实现新功能时是可选内容。</p>
	</li>
	<li>
	<p>添加对任何假设或背景信息的简短说明，这些内容可能对下一年研究此功能的其他贡献者起到很大的帮助作用。</p>
	</li>
	</ul>

	<p>以下是一个示例提交消息：</p>
	<pre class="devsite-click-to-copy">short description on first line

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

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

	<h3 id="upload-to-gerrit">上传到 Gerrit</h3>
	<p>将更改提交到您的个人历史记录后，请使用以下命令将其上传到 Gerrit：</p>
	<pre class="devsite-terminal devsite-click-to-copy">
	repo upload
	</pre>
	<p>如果您在同一存储库中新建了多个分支，则系统会提示您选择要上传的分支。</p>
	<p>上传成功后，Repo 会为您提供 <a href="https://android-review.googlesource.com/">Gerrit</a> 上对应新页面的网址。访问该链接可在审核服务器上查看您上传的补丁程序、添加注释，或者为您的补丁程序申请特定审核者。</p>
	<h3 id="uploading-a-replacement-patch">上传替换补丁程序</h3>
	<p>假设某位审核者已看过您的补丁程序，并要求您做一些小小的修改。您可以在 Git 中修改提交的内容，这会在 Gerrit 中生成一个新的补丁程序，该补丁程序与原始补丁程序具有相同的更改 ID。</p>
	<aside class="note"><b>注意</b>：如果您在上传该补丁程序之后进行了其他提交，那么您将需要手动移动 Git HEAD。</aside>
	<pre class="devsite-click-to-copy">
	<code class="devsite-terminal">git add -A</code>
	<code class="devsite-terminal">git commit --amend</code>
	</pre>
	<p>当您上传修改后的补丁程序时，它将替换 Gerrit 和本地 Git 历史记录中的原始补丁程序。</p>

	<h3 id="resolving-sync-conflicts">解决同步冲突</h3>
	<p>如果提交到源代码树的其他补丁程序与您的存在冲突，那么您需要在源代码存储库的新 HEAD 的基础上对您的补丁程序执行“衍合”(rebase) 命令。执行此操作的一种简单方法是运行以下命令：</p>
	<pre class="devsite-terminal devsite-click-to-copy">
	repo sync
	</pre>
	<p>此命令首先从源代码服务器获取更新，然后尝试在新的远程 HEAD 的基础上对您的 HEAD 自动执行衍合命令。</p>
	<p>如果自动衍合命令失败，您就必须手动执行衍合。</p>
	<pre class="devsite-terminal devsite-click-to-copy">
	repo rebase
	</pre>
	<p>使用 <code>git mergetool</code> 可帮助您处理衍合冲突。在成功合并冲突文件后，运行以下命令：</p>
	<pre class="devsite-terminal devsite-click-to-copy">
	git rebase --continue
	</pre>
	<p>在自动或手动衍合完成之后，运行 <code>repo
	upload</code> 来提交衍合后的补丁程序。</p>

	<h3 id="after-a-submission-is-approved">提交内容获得批准后</h3>
	<p>在提交内容通过审核和验证流程之后，Gerrit 会自动将更改合并到公开存储库。其他用户可以运行 <code>repo sync</code> 将更新提取到自己的本地客户端。</p>

	<h2 id="upstream-projects">上游项目</h2>
	<p>Android 使用了许多其他开源项目，例如<a href="/setup/code-lines.html">代码流水线、分支和版本</a>中所述的 Linux 内核和 WebKit。对于 <code>external/</code> 下的大多数项目，如果要提交更改，则应该在上游进行，然后 Android 维护者会收到有关包含这些更改的新上游版本的通知。上传补丁程序也可能有助于我们跟踪新的上游版本，但如果是 Android 中广泛使用的项目（如下面提到的大多数大型项目），我们将很难做出更改。在这种情况下，我们倾向于在每次发布版本时进行升级。</p>
	<p>一个有趣的特殊情况是 Bionic。由于大部分代码都是来自 BSD，因此，除非更改涉及对 Bionic 新内容的编码，否则我们宁愿使用上游修复程序，然后从相应的 BSD 中提取一个全新文件。（可惜的是，我们目前有各种不同的 BSD，但我们希望将来能够解决该问题，并能够更密切地跟踪上游项目。）</p>
	<h3 id="icu4c">ICU4C</h3>
	<p>对于 <code>external/icu4c</code> 中的 ICU4C 项目，所有更改都应通过 <a href="http://site.icu-project.org/">icu-project.org/</a> 在上游进行。
	如需了解详情，请参阅<a href="http://site.icu-project.org/bugs">提交 ICU 错误和功能请求</a>。</p>

	<h3 id="llvmclangcompiler-rt">LLVM/Clang/Compiler-rt</h3>
	<p>对于与 LLVM 相关的项目（<code>external/clang</code>、<code>external/compiler-rt</code>、<code>external/llvm</code>），所有更改都应通过 <a href="http://llvm.org/">llvm.org/</a> 在上游进行。</p>

	<h3 id="mksh">mksh</h3>
	<p>对于 <code>external/mksh</code> 中的 MirBSD Korn Shell 项目，所有更改都应在上游进行：通过向 [email protected] 发送电子邮件（无需订阅即可提交），或者在 <a href="https://launchpad.net/mksh">Launchpad</a> 中进行（可选）。
	</p>
	<h3 id="openssl">OpenSSL</h3>
	<p>对于 <code>external/openssl</code> 中的 OpenSSL 项目，所有更改都应通过 <a href="http://www.openssl.org">openssl.org</a> 在上游进行。</p>
	<h3 id="v8">V8</h3>
	<p>对于 <code>external/v8</code> 中的 V8 项目，所有更改都应通过 <a href="https://code.google.com/p/v8">code.google.com/p/v8</a> 在上游提交。如需了解详情，请参阅<a href="https://code.google.com/p/v8/wiki/Contributing">为 V8 贡献代码</a>。</p>
	<h3 id="webkit">WebKit</h3>
	<p>对于 <code>external/webkit</code> 中的 WebKit 项目，所有更改都应通过 <a href="http://www.webkit.org">webkit.org</a> 在上游进行。该过程需从提交 WebKit 错误开始。
	只有当该错误仅限于 Android 时，才可以在 <code>Platform</code> 和 <code>OS</code> 字段中使用 <code>Android</code>。如果附有建议的修复程序并包含测试结果，则错误更有可能引起审核者的注意。如需了解详情，请参阅<a href="http://webkit.org/coding/contributing.html">为 WebKit 贡献代码</a>。</p>
	<h3 id="zlib">zlib</h3>
	<p>对于 <code>external/zlib</code> 中的 zlib 项目，所有更改都应通过 <a href="http://zlib.net">zlib.net</a> 在上游进行。</p>

	</body></html>