源代码管理¶

本节中概述的信息旨在为 Git 成为项目事实来源的未来做准备。

提交表示¶

WebKit 项目严重依赖 main 分支上的线性、有序历史记录来跟踪项目中的回归。历史上，Subversion 的修订版被用于我们的提交消息、错误跟踪和服务中以实现此目标。我们迁移到 git 需要一个新的解决方案，因为虽然 git 能够强制执行线性有序历史记录（只要禁止合并提交），但 git 提交传统上表示为哈希值，这些哈希值不像 Subversion 的修订版那样易于排序。

WebKit 团队转而采用了一种系统，其中提交根据它们与默认分支的关系以及它们的祖先数量来表示，我们称这种表示为提交标识符。大多数工具都接受 git 哈希、Subversion 修订版和标识符，尽管如果需要，Tools/Scripts/git-webkit 脚本可以在本地在这三种表示之间进行转换。

为了在本地开发中使用这种提交表示，Tools/Scripts/git-webkit 实现了一个 blame 和 log 子命令，如果可用，它们将包含提交标识符和Subversion 修订版。

Tools/Scripts/git-webkit blame Makefile

230258@main (Keith Rollin    2020-10-08 19:10:32 +0000  1) MODULES = Source Tools
184786@main (Jonathan Bedard 2017-02-02 18:42:02 +0000  2) 
229628@main (Keith Rollin    2020-09-22 18:37:51 +0000  3) define build_target_for_each_module
229628@main (Keith Rollin    2020-09-22 18:37:51 +0000  4)      for dir in $(MODULES); do \
229628@main (Keith Rollin    2020-09-22 18:37:51 +0000  5)              ${MAKE} $@ -C $$dir PATH_FROM_ROOT=$(PATH_FROM_ROOT)/$${dir}; \
229628@main (Keith Rollin    2020-09-22 18:37:51 +0000  6)              exit_status=$$?; \
229628@main (Keith Rollin    2020-09-22 18:37:51 +0000  7)              [ $$exit_status -ne 0 ] && exit $$exit_status; \
229628@main (Keith Rollin    2020-09-22 18:37:51 +0000  8)      done; true
229628@main (Keith Rollin    2020-09-22 18:37:51 +0000  9) endef
...

Tools/Scripts/git-webkit log

commit 240867@main (989ff515ce6e103271072dd1b397ac43572a910c, r281493)
Author: Adrian Perez de Castro <aperez@igalia.com>
Date:   Tue Aug 24 13:48:35 2021 +0000

    Non-unified build fixes, late August 2021
    https://bugs.webkit.org/show_bug.cgi?id=229440

    Unreviewed non-unified build fixes.
...

标识符¶

标识符是 WebKit 团队用来指代我们团队开发的提交表示形式的术语，该表示形式根据提交与默认分支的关系以及提交的祖先数量来唯一标识提交。

提交标识符的形式如下

<branch-point>.<number>@<branch>

其中 branch 是提交所在 git 分支的名称，number 是该提交拥有的祖先数量（如果提交位于默认分支上），或者是该提交自默认分支分歧以来的祖先数量（如果提交不在默认分支上），而 branch-point 可选地显示该提交在默认分支上的祖先数量（仅与不在默认分支上的提交相关）。

下面的时间线显示了多个分支下的标识符样式

                      ———— o ————————————— o
                    /      |               |
                   /  101.2@branch-b  101.3@branch-b
                  ——————— o ———————————— o
                /         |              |
           /   101.1@branch-a  101.2@branch-a
——— o ———————— o ———————— o ——————— o ——————— o
    |          |          |         |         |
 100@main   101@main   102@main  103@main  104@main

值得注意的是，提交，尤其是在分支上的提交，可以有多个有效的标识符。在上面的例子中，101.1@branch-a 也可以被称为 101.1@branch-b，而 101@main 可以被称为 101.0@branch-a。WebKit 团队已将给定提交的规范标识符定义为该提交在最不具体的分支上的标识符。分支具体性的衡量标准在 Tools/Scripts/libraries/webkitscmpy/webkitscmpy/scm_base.py 中有所概述，但可以基本理解为：

default branch                               (least specific)
production branches
    "a" branch name
    "z" branch name
development branches (eng/*, dev/*. ect.)
    "a" branch name
    "z" branch name                          (most specific)

本机 git 引用和标识符之间的转换可以使用 Tools/Scripts/git-webkit find 完成

Tools/Scripts/git-webkit find safari-611-branch

Title: Unreviewed build fix, rdar://problem/76412930
Author: Russell Epstein <repstein@apple.com>
Date: Fri Apr 16 14:34:51 2021
Revision: 276171
Hash: 67dd5465d8f5
Identifier: 232923.433@remotes/fork/safari-611-branch

git-webkit find 232923.400@safari-611-branch

Title: Revert "Cherry-pick r271794. rdar://problem/76375364"
Author: Commit Queue <commit-queue@webkit.org>
Date: Thu Apr 15 13:15:48 2021
Revision: 276064
Hash: dd1f0d38426c
Identifier: 232923.400@remotes/fork/safari-611-branch

或者如果没有可用检出，则通过 commits.webkit.org 完成

curl https://commits.webkit.org/safari-612-branch/json

{
    "author": {
        "emails": [
            "repstein@apple.com"
        ],
        "name": "Russell Epstein"
    },
    "branch": "safari-612-branch",
    "hash": "76f038bbe2889a3714c6176b3c9e35b404c57e35",
    "identifier": "240672.6@safari-612-branch",
    "message": "Versioning.\n\nWebKit-7612.2.1\n\nCanonical link: https://commits.webkit.org/240672.6@safari-612-branch\ngit-svn-id: https://svn.webkit.org/repository/webkit/branches/safari-612-branch@281269 268f45cc-cd09-0410-ab3c-d52691b4dbfc",
    "order": 0,
    "repository_id": "webkit",
    "revision": 281269,
    "timestamp": 1629406217
}

分支管理¶

WebKit 项目旨在保持分支清洁，开发应主要在开发者拥有的仓库分支（forks）上进行，而不是直接在 WebKit 仓库本身上进行。推送到 WebKit 仓库的分支应为生产分支或由自动化工具拥有的临时分支。

生产分支¶

大多数 WebKit 开发应在我们的默认分支 main 上进行。请注意，Subversion 的 trunk 分支跟踪的提交集与现代 main 分支相同。main 受提交队列保护，如权限标题中所述。

其他生产分支由特定平台作为其发布周期的一部分进行管理。最值得注意的是，safari-*-branch 系列分支对应于 Apple 发布的 WebKit 版本。

临时分支¶

分支可以由自动化工具和与自动化工具交互的贡献者临时添加。这些分支预计在添加到项目后 48 小时内被删除。提交队列是其中最显著的例子。名为 commit-queue/* 和 fast-commit-queue/* 的分支代表通过验证过程后将提交到生产分支的代码。（注：正在进行中）

合并提交¶

WebKit 项目禁止在生产分支上进行合并提交。

合并提交是一种 git 提交，它可能具有多个父级，合并提交的历史记录看起来像这样：

                  ——— o ———————————— o ————
                /                           \
           /                             \ 
——— o ———————— o ———————— o ——————— o ——————— o ——————— o

合并提交会使二分查找变得困难，并且当反向追溯时，人类难以理解特定提交中的代码。因此，所有生产分支都禁止合并提交。

权限¶

只有管理员和提交队列才能直接访问 main。相反，提交者被授予推送名为 commit-queue/* 和 fast-commit-queue 的分支的权限，这些分支在被 rebase 并合并到 main 之前会进行检查（注：正在进行中）。

匹配 safari-*-branch 的分支由 Apple 集成者管理。

规范化¶

为了使标识符更易于使用，提交队列通过指向 commits.webkit.org 的链接将这些标识符添加到提交消息中。我们称此过程为“规范化”。除了将标识符添加到提交消息中之外，规范化还尝试解析提交消息，以正确归因可能由不同贡献者编写和提交的更改。

规范化任务由提交队列负责，并在将更改推送到生产分支之前立即完成。不应在非生产分支上执行规范化。