发布 geckodriver

当项目的主仓库在 GitHub 上时，发布 geckodriver 比现在要简单得多。如今，geckodriver 托管在 mozilla-central 中，虽然我们希望将来能够从 Mozilla 的 CI 基础设施 中发布版本，但我们目前处于两个世界之间：开发发生在 m-c 中，但版本继续从 GitHub 发布。

无论如何，发布 geckodriver 的步骤如下：

更新树内依赖项

geckodriver 依赖于许多也位于 central 中的 Rust crate，并使用相对路径。以下是其 Cargo.toml 文件中的摘录：

[dependencies]
…
marionette = { path = "./marionette" }
…
mozdevice = { path = "../mozbase/rust/mozdevice" }
mozprofile = { path = "../mozbase/rust/mozprofile" }
mozrunner = { path = "../mozbase/rust/mozrunner" }
mozversion = { path = "../mozbase/rust/mozversion" }
…
webdriver = { path = "../webdriver" }

因为我们需要在发布时将 geckodriver 源代码导出到旧的 GitHub 仓库，所以如果自上次发布以来这些 crate 发生过任何更改，我们需要按照指定的顺序先发布这些 crate。如果它们没有发生任何更改，则可以跳过它们。

  • testing/mozbase/rust/mozdevice

  • testing/mozbase/rust/mozprofile

  • testing/mozbase/rust/mozrunner

  • testing/mozbase/rust/mozversion

  • testing/webdriver

  • testing/geckodriver/marionette

对于每个 crate：

  1. 切换到 crates 文件夹。

  2. 根据 语义版本控制规则，在 Cargo.toml 中更新版本号，并更新使用当前修改的 crate 的其他树内 crate 的版本依赖项。请注意，如果错过了更新 crate 的依赖项，则运行 cargo update 将失败。

  3. 使用 cargo-semver-checks 命令验证版本更改。

    % cargo semver-checks check-release

  4. 更新 crate。

    % cargo update -p <crate name>

  5. 我们还根据 Mozilla 的 审计标准 发布 crate 的审计信息。因为我们使用 通配符审计条目，所以请确保最新的发布日期仍在 end 日期内。crate 的相关条目可以在 audits.toml 的顶部找到。如果日期已过，则将其值更新到最多一年后的未来。

  6. 提交修改后的 Cargo.toml 文件、Cargo.lock 和 audits.toml 的更改。

    % git add Cargo.toml Cargo.lock audits.toml testing
% git commit -m "Bug XYZ - [rust-<name>] Release version <version>"

更新变更日志

geckodriver 的重大更改在 CHANGES.md 中进行了说明。许多用户依赖于此，因此确保其 **与最终用户相关** 非常重要。例如，我们只提及对用户可见的更改。变更日志不是提交的完整汇编，因为这些提交通常不会向最终用户传达更改的本质。如果添加了一个功能但在发布前被删除，则没有理由将其列为更改。

最好也包含来自 webdriver、marionette、rust-mozrunner 和 rust-mozdevice crate 的相关信息，因为这些是 geckodriver 最重要的依赖项，并且它的许多功能都在那里实现。

要获取上述 crate 中所有更改的列表，可以使用以下命令之一：

% hg log -M -r <revision>::central --template "{node|short}\t{desc|firstline}\n" <path>
% git log --reverse $(git cinnabar hg2git <revision>)..HEAD --pretty="%s" <path>

其中 <revision> 是上次 geckodriver 版本的变更集，<path> 是仓库中 crate 的位置。

将更改列表添加到 Bugzilla 上的相关版本错误中，并检查错误的依赖项列表以查找其他值得提及的修复。

我们遵循现有变更日志的写作风格，每个版本（带发布日期）一个部分，包含“新增”、“更改”、“修复”和“移除”子部分。如果目标 Firefox 或 Selenium 版本已更改，最好进行说明。行在文本编辑器和渲染的 HTML 中都以大约 72 列的格式进行优化，以便于阅读。fmt(1) 在文本格式化方面做得非常好。

更新版本号和支持页面

在 Cargo.toml 中将版本号更新到下一个版本。geckodriver 遵循 语义版本控制，因此在确定版本号之前最好先熟悉一下。

更改版本号后，运行

% ./mach build testing/geckodriver

再次更新 Cargo.lock。

现在更新 支持页面，在版本表中添加新行，包括所需的 Selenium 和 Firefox 版本。

最后提交所有这些更改。

添加变更集 ID

为了在克隆仓库后轻松地允许 geckodriver 的发布构建，必须将发布的变更集 ID 添加到变更日志中。因此，在补丁系列中添加一个最终的占位符提交，以便提前进行审查。

一旦补丁系列的所有先前修订版都已落地并合并到 mozilla-central 中，就必须从合并提交中选择变更集 ID 以完成变更日志。需要此特定 ID，因为 Taskcluster 基于该合并创建最终的签名版本。

发布新的树内依赖项

确保等到上述完整的补丁系列合并到 mozilla-central。然后继续执行以下步骤。

在发布 geckodriver 之前，所有依赖项 crate 必须先发布，如 前面更新 所述。

因此，切换到每个已更新的 crate 的目录，并运行以下命令以发布 crate：

% cargo publish

请注意，如果 crate 有树内依赖项，请确保首先更改依赖项信息。

现在不要发布 geckodriver crate！

一旦所有 crate 都已发布，请观察 mozilla-central 仓库根目录下的 /target/package/ 文件夹，并删除与上述已发布包相关的所有文件夹（这将节省约 1GB 的磁盘空间）。

导出到 GitHub

规范的 GitHub 仓库是 https://github.com/mozilla/geckodriver.git，请确保您拥有该仓库的本地克隆。它有三个分支：master，仅包含 README.md；old，是项目导出到 mozilla-central 时的状态；以及 release，从该分支发布版本。

在将代码复制到 GitHub 仓库之前，我们需要在 mozilla-central 上检出 更新版本号的发布提交

% hg update $RELEASE_REVISION

或者

% git checkout $(git cinnabar hg2git $RELEASE_REVISION)

我们现在将 testing/geckodriver 的内容导出到基于 release 分支的新分支，该分支将用于创建拉取请求。

% cd $SRC/geckodriver
% git checkout release
% git pull
% git checkout -b do_release_X.Y.Z
% git rm -rf .
% git clean -fxd
% cp -rt $SRC/gecko/testing/geckodriver .

现在通过运行以下命令验证 geckodriver 是否可以正确构建：

% cargo build

提交本地更改

现在将您在本地对 release 分支所做的所有更改提交。建议设置 GPG 密钥 以对提交进行签名，以便将发布提交标记为 verified。

% git add . -- ':!mach_commands.py :!moz.build :!target/*'
% git commit -S -am "Import of vX.Y.Z" (signed)

或者，如果您无法使用签名，请使用

% git add . -- ':!mach_commands.py :!moz.build :!target/*'
% git commit -am "Import of vX.Y.Z" (unsigned)

然后推送更改并创建拉取请求。

% git push origin do_release_X.Y.Z

如上所述，您对此分支所做的更改不会上游到 mozilla-central。它仅用作外部使用者构建自己的 geckodriver 版本的位置。

发布版本

geckodriver 需要在 github.com 上手动发布。因此，开始 创建新的版本，并进行以下更改：

  1. 指定“标签版本”，并选择“发布”作为目标。

  2. 将版本标题保留为空。

  3. 将 CHANGES.md 中的原始 Markdown 源粘贴到描述字段中。这将突出显示最终用户在访问 GitHub 下载部分时在该特定包中所做的更改。确保检查所有引用是否都可以解析，如果不能，请确保也添加这些引用。

  4. 通过将 %changeset% 替换为完整的发布变更集 ID，在 taskcluster 索引 中查找签名的 geckodriver 存档。重命名各个文件，以便基本名称看起来像 ‘geckodriver-v%version%-%platform’。上传所有文件，包括 Linux 平台的校验和文件。

  5. 在 GitHub 上宣布发布之前，还请通过从 release 分支运行 cargo publish 发布 crates.io 上的 geckodriver crate。

  6. 将发布公告发送到 dev-webdriver 邮件列表。

恭喜！您已发布 geckodriver！