贡献代码

本页面描述了如何向 WebKit 源代码控制仓库贡献更改。WebKit 项目维护了几个脚本来协助您。本页面假设您已经知道如何检出和构建代码。

概述

以下是推荐的步骤。本页面的后续部分将更详细地解释每个步骤。

  1. 创建或登录您的 WebKit Bugzilla 账户。
  2. 选择或创建一个要处理的bug 报告。
  3. 开发您的更改。
  4. 确保您的更改符合代码风格指南。check-webkit-style 脚本可能会有所帮助。
  5. 使用 run-webkit-tests 脚本运行布局测试，并确保它们全部通过。有关更多信息，以及如果您修改了 JavaScriptCore 需要做的事情，请参阅测试页面。
  6. 将所有新文件添加到您的工作目录。
  7. 使用Tools/Scripts/git-webkit setup配置您的 WebKit 检出以进行上传拉取请求。
  8. 使用 git commit -a 提交您的本地更改，之前运行的 git-webkit setup 命令将配置一个提交消息模板
  9. 运行 Tools/Scripts/git-webkit pull-request 将您的提交上传到 GitHub 进行审查
  10. 根据审阅者的建议进行任何更改。
  11. 审查通过后，请某人通过合并队列 (Merge-Queue)集成您的更改。
  12. 请留意它可能导致的任何回归（希望没有）！
    Flow chart on how to submit a patch
提交补丁的流程图

有关这些步骤的更多详细信息如下。

选择一个 Bug 报告

bugs.webkit.org 数据库是 WebKit 贡献的中心交流点。几乎每项贡献都对应着一个 bug 报告。请注意，WebKit 使用 bug 报告来跟踪所有类型的代码更改，而不仅仅是 bug 修复。选择一个要处理的 bug 报告。您也可以创建一个新报告。在创建新报告之前，请务必搜索数据库以避免重复。选择 bug 报告后，请遵循 WebKit bug 生命周期指南进行报告。例如，如果您正在处理某个问题，通常最好在报告中评论。如果您的更改可能存在争议，您可能需要提前与 webkit-dev 邮件列表确认。

开发您的更改

如果您对文件进行实质性更改，您可能希望为自己或为您工作的公司添加版权行。下面是个人贡献者和公司的版权行示例：Copyright (C) 2011 John Smith (jsmith@example.com) Copyright (C) 2011 Company Inc. All rights reserved. 此外，请确保您引入的任何新源代码和脚本文件在文件开头包含许可文本。如果您是新文件的作者，可以在此处找到首选的许可文本：WebCore/LICENSE-APPLE。（页面底部的“原始格式”链接包含更易于剪切和粘贴的文本。）只需用您自己的信息替换版权行，例如上面建议的那样。

代码风格指南

补丁必须符合代码风格指南。代码库的一些旧部分不遵循这些指南。如果您正在修改此类代码，通常最好对其进行清理以符合当前指南。遗留组件是例外，不应进行清理。如果您使用 webkit-patch upload，您的补丁将在上传前自动检查风格合规性。您可以通过运行 Tools/Scripts/check-webkit-style 脚本手动检查风格。补丁上传后，WebKit 早期预警系统也将检查风格。

回归测试

完成更改后，您需要运行回归测试，这通过 run-webkit-tests 脚本完成。所有测试都必须通过。如果补丁破坏现有布局测试，将不会被集成到代码库中。对于任何影响布局引擎的功能，必须构建新的回归测试。如果您提供的补丁修复了 bug，该补丁还应包括添加一个在没有补丁时会失败、有补丁时会成功的回归测试。如果没有提供回归测试，审阅者会要求您修改补丁，因此您可以提前构建测试并确保它附在 bug 上，从而节省时间。如果无法（或不需要）为修复构建布局测试，您必须向审阅者解释为什么不需要新测试。

JavaScriptCore 的测试

如果您对 JavaScriptCore 进行了更改，请执行 run-javascriptcore-tests 脚本。该脚本将运行所有测试并总结结果与当前预期结果的不同之处。

将新文件添加到您的工作目录

如果您的更改包括添加新文件（例如新的布局测试），请使用 git add 命令将这些文件标记为要添加到仓库。如果您不这样做，您下面生成的补丁文件中将缺少新文件。您可以从 git 的在线文档或通过使用 git --help 命令了解更多关于 git add 等 git 命令的信息。

设置检出

WebKit 有许多我们建议您应用于 WebKit 检出的配置。我们的维基详细说明了这些配置是什么，我们通过 Tools/Scripts/git-webkit setup 自动化了此设置，并建议贡献者在上传拉取请求之前运行此脚本。

提交消息

WebKit 项目期望比许多项目更详细的提交消息。Tools/Scripts/git-webkit setup 将在您的 WebKit 检出中的 .git/hooks/prepare-commit-msg 配置一个钩子，当您本地提交时，它将准备一个提交消息模板。使用此模板编写您所做更改的简要摘要。不必担心“Reviewed by NOBODY (OOPS!)”这一行，审阅您更改的人会填写。一个典型的提交消息条目在被集成之前看起来像这样：

Font::glyphDataAndPageForCharacter doesn't account for text orientation when using systemFallback on a cold cache.
https://bugs.webkit.org/show_bug.cgi?id=98452.

Reviewed by NOBODY (OOPS!).

The text orientation was considered only when there is a cache hit.
This change moves the logic to handle text orientation to a separate
inline function that is called also when the glyph is added to the cache.

Test: fast/text/vertical-rl-rtl-linebreak.html

* platform/graphics/FontFastPath.cpp:
(WebCore::applyTextOrientationForCharacter): Added.
(WebCore::Font::glyphDataAndPageForCharacter): Modified to use the new function in
both cases of cold and warm cache.

如果工具未检测到测试用例的添加，则会出现“No new tests. (OOPS!)”这一行。如果您的补丁不需要测试用例（或测试用例不可能），请删除此行并解释为什么没有编写测试。否则，所有更改都需要测试用例，并且应在提交消息中提及。如果您在提交消息条目中保留此行，您的补丁将被合并队列 (Merge-Queue)拒绝。

回复审阅者

WebKit 审阅者必须批准您的补丁，WebKit 才能将其接受到源代码控制仓库中。审阅者通常会批准您的补丁（通过在 bug 报告中回复 r=me 并在 GitHub 中将拉取请求标记为 Approved）或要求修改您的补丁（并在拉取请求上 Request changes）。在极少数情况下，补丁可能会被永久拒绝，这意味着审阅者认为该功能不应被提交到代码库中。审查过程可能包括您和审阅者之间多次迭代，因为您会提交修订后的补丁。

集成到代码库

更改获得批准后，您应该请提交者或审阅者通过合并队列 (Merge-Queue)集成您的补丁。

保持代码库健康

无论是哪种情况，您的补丁责任不会随着补丁集成到代码库而结束。您的更改可能导致回归，或者补丁集成后审阅者可能会提供额外反馈。您可以在 build.webkit.org 监控代码库，确保您的补丁在所有平台上都能构建并通过测试。如果出现回归，您有责任及时处理，并回应集成后出现的额外反馈。更改应在所有平台上成功，但要测试 WebKit 支持的每个平台可能很困难。请务必通过比较更改前后失败测试列表，确保您的更改不会在流量大的 Mac 或 Windows 端口上引入新的测试失败。您的更改至少必须在所有平台上编译通过。

合并队列

WebKit 通过合并队列（Merge-Queue）或不安全合并队列（Unsafe-Merge-Queue）集成所有更改。提交者可以为拉取请求添加 merge-queue 或 unsafe-merge-queue 标签，以便将该拉取请求合并到生产分支。合并队列将阻止集成破坏构建的更改，因此强烈建议使用此集成方法，除非更改有令人信服的理由需要更快地集成且验证较少。有关更多详细信息，请参阅我们的 GitHub 维基。

获得提交和审查权限

我们的提交者和审阅者政策提供了关于获得提交和审查权限的详细信息。