moz-phab

Mozilla的Phabricator CLI，支持提交一系列提交。

安装

moz-phab可以使用pip3 install MozPhab进行安装。

有关详细安装说明，请参阅

• Windows安装说明
• Linux安装说明
• macOS安装说明

moz-phab将定期检查更新，并在可用时无缝安装最新版本。要强制更新moz-phab，请运行moz-phab self-update。

变更日志

变更日志可在Mozilla Wiki上的MozPhab页面找到。

配置

moz-phab有一个INI风格的配置文件来控制默认值：~/.moz-phab-config

如果不存在，该文件将被创建。

[ui]
no_ansi = False

[vcs]
safe_mode = False

[git]
remote =
command_path =

[hg]
command_path =

[submit]
auto_submit = False
always_blocking = False
warn_untracked = True

[patch]
apply_to = base
create_bookmark = True
create_topic = False
create_branch = True
always_full_stack = False
branch_name_template = phab-D{rev_id}
create_commit = True

[updater]
self_last_check = 0
self_auto_update = True
get_pre_releases = False

[error_reporting]
report_to_sentry = True

• ui.no_ansi : 永远不使用ANSI颜色（默认：自动检测）。
• vcs.safe_mode : 仅使用安全的VCS设置（默认：False）。使用--safe-mode选项将其切换为一次性使用。
• git.remote: 以逗号分隔的字符串。默认远程用于找到第一个未发布的提交。默认为空字符串，表示将从git remote命令读取远程列表。
• git.command_path：Git二进制文件的命令路径。
• hg.command_path：Mercurial二进制文件的命令路径。
• submit.auto_submit：当设置为 True 时，将跳过确认提示（默认：False）。
• submit.always_blocking：当设置为 True 时，提交描述中的审阅者将被标记为阻塞。命令行中指定的审阅者将覆盖此设置（默认：False）。
• submit.warn_untracked：当设置为 True 时，如果在工作目录中有未提交或未跟踪的更改，将显示警告（默认：True）。
• patch.apply_to：默认应用补丁的位置。[base/here]。如果设置为 "base"，则 moz-phab 将在第一个提交中查找 SHA1。如果设置为 "here"，则使用当前提交/检出（默认：base）。
• patch.create_bookmark：仅影响修补 Mercurial 仓库时。如果设置为 True，moz-phab 将为新 DAG 分支点创建一个书签（基于最后一个修订号）。
• patch.create_topic：仅影响修补 Mercurial 仓库时。需要启用 topic 扩展。如果设置为 True，moz-phab 将为新 DAG 分支点创建一个主题（基于最后一个修订号）。
• patch.create_branch：仅影响修补 Git 仓库时。如果设置为 True，moz-phab 将为新 DAG 分支点创建一个分支（基于最后一个修订号）。
• patch.always_full_stack：当设置为 False 且修补的修订有后续者时，moz-phab 将询问是否应该修补整个堆栈。如果设置为 True，moz-phab 将不询问而直接执行。
• patch.branch_name_template：用于命名新分支、主题或书签的模板字符串。该字符串接受单个格式化字符串输入 rev_id，它是正在修补的修订的 ID。
• patch.create_commit：如果设置为 True（默认值），将为补丁生成一个提交。使用 patch 命令应用更改。
• updater.self_last_check：表示此脚本上次执行更新检查的时间戳（本地时区）。设置为 -1 以禁用此检查。
• self_auto_update：当设置为 True 时，如果可用新版本，moz-phab 将自动更新。如果设置为 False，moz-phab 将仅警告新版本。
• get_pre_releases：当设置为 True 时，moz-phab 自动更新将获取预发布版本（如果可用），否则将忽略预发布版本（默认：False）。
• error_reporting.report_to_sentry：当设置为 True 时，moz-phab 将将异常提交给 Sentry，以便 moz-phab 开发者可以查看未报告的错误。

环境变量

moz-phab 还可以通过以下环境变量进行配置：

• DEBUG：启用调试输出（默认：禁用）。
• MOZPHAB_NO_USER_CONFIG：不要从或写入 ~/.moz-phab-config（默认：禁用）。
• DISABLE_SPINNER：设置环境变量以禁用旋转器（默认：旋转器启用）。

执行

要获取有关所有可用命令的信息，请运行

moz-phab -h

涉及 VCS（如 submit 和 patch）的所有命令都可以与 --safe-mode 开关一起使用。它将以所选扩展集执行 VCS 命令。

向 Phabricator 提交提交

最简单的调用是

moz-phab [start_rev] [end_rev]

如果没有指定位置参数（start_rev/end_rev），则会自动确定提交范围，从第一个非公开、非废弃的更改集（对于Mercurial）或第一个未发布的提交（对于Git）开始，以当前签出的更改集结束。如果至少提供了一个参数，moz-phab将遵循底层VCS的log行为。在Mercurial中（作为包含），Git中（排除）对第一个参数的解释不同。如果只提供了一个参数，则范围结束再次解释为当前签出的更改集。如果提供了两个参数，则第二个参数解释为包含。

默认情况下，Bug ID和审查者会从提交消息中解析出来。您可以通过在审查者的昵称后附加感叹号来设置审查者为阻塞，例如r=foo!。如果submit.always_blocking设置为true（见上文），则无论何种情况，审查者都将设置为阻塞。

Bug ID也可以通过--bug选项为系列中的每个修订版设置，这将覆盖提交消息中的任何Bug ID。同样，可以通过--reviewer（常规审查者）和/或--blocker（阻塞审查者）为系列中的每个修订版设置审查者，这再次覆盖了提交消息中的任何审查者。

运行moz-phab submit -h以获取提交修订版的更多选项。

要提交提交系列的更新，以相同的方式运行moz-phab并使用相同的参数，即指定完整的原始提交范围。请注意，尽管插入和修改提交应该可以正常工作，但尚未支持重新排序提交，删除提交将留下相关的修订版，应该手动放弃。有关计划修复的内容，请参阅bug 1481539。另外，请注意，“修复”提交尚未支持；请参阅bug 1481542。

从Phabricator下载补丁

moz-phab patch允许对整个修订版堆栈进行修补。最简单的调用方式是

moz-phab patch revision_id

要修补以修订D123结束的堆栈，请运行moz-phab patch D123。差异将从Phabricator下载并使用底层VCS（Mercurial的import或Git的apply）应用。将为每个修订版创建一个新书签或主题（Mercurial）或分支（Git）中的提交。

可以使用以下选项修改此行为

• --apply-to TARGET 定义应用补丁的提交

  • base（默认）在修订版的第一代祖先中查找基础提交，
  • here 使用当前提交，
  • {NODE} 使用由SHA1或（在Mercurial中）修订号标识的提交

• --raw 从最旧的祖先开始打印每个修订版的差异，而不是将其应用到存储库中。它可以用来使用外部工具修补工作目录：$ moz-phab patch D123 --raw | patch -p1。$ moz-phab patch D123 --raw | hg import。$ moz-phab patch D123 --raw | git am。

• --no-commit 使用git apply命令（也适用于Mercurial存储库）修补差异。不会创建提交或分支。

• --no-bookmark：仅用于修补Mercurial存储库。如果不提供 - moz-phab将为新的DAG分支点创建一个书签（基于最后一个修订号）。默认行为是可配置的。

• --no-topic：仅用于修补Mercurial存储库。需要启用topic扩展。如果不提供且在配置中启用 - moz-phab将为新的DAG分支点创建一个主题（基于最后一个修订号）。默认行为是可配置的。

• --no-branch：仅用于修补Git存储库。如果不提供 - moz-phab将为分支创建一个分支（基于修订号）。否则，提交将仅添加到基础提交之上，这可能会导致存储库切换到“分离的HEAD”状态。

• --skip-dependencies：仅修补一个修订版，忽略依赖关系。

• --diff-id DIFF_ID：用于指定在修订历史中要拉取的特定差异。

重新组织堆栈

moz-phab reorg [start_rev] [end_rev] 允许您在 Phabricator 中重新组织堆栈。

如果您已经通过添加、删除或移动提交来更改了本地堆栈，您需要更改 Phabricator 中修订的父/子关系。

moz-phab reorg 命令将比较堆栈，显示将要更改的内容，并在采取任何行动之前请求许可。

可以使用以下选项修改此行为

• --no-abandon 避免在它们从本地堆栈中删除时放弃 Phabricator 上的修订。仅更改修订之间的依赖关系。

将提交关联到现有的 phabricator 修订

moz-phab 使用提交消息中的一行跟踪哪个修订与提交关联。如果您想从不同的机器或环境中处理现有修订，我们建议您使用 从 Phabricator 使用 moz-phab patch 应用现有修订。

如果出于某种原因这不可行，您可以通过在扩展提交消息中添加类似以下内容的行将新提交关联到同一修订

Differential Revision: https://phabricator.services.mozilla.com/D[revision]

将 [revision] 替换为您的修订标识符。

提交提升请求

moz-phab uplift 可用于提交用于提升的补丁到发布仓库，绕过标准发布列车周期。有关提升的更多详细信息，请参阅 发布管理wiki。

查看可以提交提升请求的列车

moz-phab uplift --list-trains

moz-phab uplift 使用与 moz-phab submit 相同的语法。要针对 mozilla-beta 提交提升请求

moz-phab uplift start_rev end_rev --train beta

当您在统一仓库（即 mozilla-unified 或 gecko-dev）内提交提升时，moz-phab uplift 将尝试将更改重置到目标列车的头部，同时保留您的 VCS 中现有的修订。从非统一仓库（即 mozilla-central、autoland 等）提交提升时，不会创建新的更改集。您可以使用 --no-rebase 禁用重置行为。

一旦您提交了请求，请导航到您堆栈的末尾提交，并使用操作菜单请求提升，就像接受修订一样。

报告问题

我们使用 Bugzilla 来跟踪开发。

在 Conduit :: moz-phab 下提交 Bugzilla 中的错误。

开发

所有 Python 代码必须使用默认设置用 black 格式化。

MacOS / Linux

1. 确保您已安装 Python 3、Git 和 Mercurial

   • 例如，在 macOS 上使用 homebrew，或使用 Linux 发行版的包管理器
   • python3、git 和 hg 可执行文件必须位于系统路径上

2. 在此仓库的克隆版本中运行以下命令（根据 Python 版本进行调整）

   python3 -m venv venv
   source venv/bin/activate
   pip3 install -r dev/requirements/python3.9.txt
   pip3 install -e .
   

3. 在做出修改后运行 moz-phab 使用 moz-phab

4. 使用 pytest -vv 运行测试

5. 使用 deactivate 退出虚拟环境

Windows

1. 安装 Python 3、Git 和 Mercurial
   • 从命令提示符运行 python3 并从 Windows 商店安装。
   • 从官方网站使用相应的安装程序安装 Git 和 Mercurial。
   • python3、git 和 hg 可执行文件必须位于系统路径上
2. 在此仓库的克隆版本中运行以下命令
   • python3 -m venv venv
   • venv\Scripts\pip3 install -r dev-requirements.txt
   • venv\Scripts\pip3 install -e .
3. 在做出修改后运行 moz-phab 使用 venv\Scripts\moz-phab
4. 要运行测试，请使用venv\Scripts\pytest -vv

重新生成需求文件

需求文件（位于dev/requirements目录中）是使用pip-tools自动生成的。这些需求文件用于CircleCI配置中，以在CircleCI上远程安装需求。您可以使用Docker来重新生成这些文件。

在Linux上

要生成dev/requirements/python*.*.txt，请在dev目录中运行以下命令

• docker-compose run generate-python3.8-requirements
• docker-compose run generate-python3.9-requirements
• docker-compose run generate-python3.10-requirements

在Windows上

要生成dev/requirements/windows.txt，请确保您没有在WSL模式下运行Docker，然后运行以下命令

• docker-compose run generate-windows-requirements

Circle CI

mozphab使用Circle CI来确保在macOS、Linux和Windows上所有测试都通过。

为确保您的更改有效，请在本地运行circleci。

1. 确保您已安装circleci客户端，请参阅CircleCI CLI文档
2. 在您的仓库克隆中，运行：circleci local execute --job test_3_8

这将在容器化环境中运行所有Python 3.8测试。这一步需要一些时间，所以您可能想像上面解释的那样运行pytest来处理您的更改。

Windows上的Circle CI

截至本文写作时，Windows上的circleci-cli不允许您在本地执行Windows测试。当CircleCI远程运行您的Windows测试时，它将使用配置为使用特殊Windows执行器的Windows Orb，该执行器预先加载了各种开发包。Windows虚拟机将使用Miniconda来引导Python环境，这可能在安装附加需求时引起一些问题。用于为Windows生成需求文件的generate-windows容器可以用于运行您的测试，以及测试包安装。要这样做，请运行以下命令

• docker-compose run generate-windows powershell.exe
• cd C:\review
• pip install dev\requirements\windows.txt
• pytest

提交补丁

不接受Pull Requests；请使用moz-phab通过Phabricator提交更改。

1. 请参阅设置
2. 一旦您的补丁在本地编写并提交，请运行moz-phab将其发送到Phabricator。

本地环境

通过使用suite，您可以在具有自己的Phabricator、BMO、Hg和其他服务实例的本地环境中运行。

这允许对moz-phab进行更彻底的集成测试，而不会影响生产数据。

您可以通过调用以下命令来让suite使用您的本地代码

docker-compose -f docker-compose.yml -f docker-compose.review.yml run local-dev

创建发布版本

要为moz-phab创建新版本

1. 创建与版本号匹配的标签。这将启动CircleCI作业以生成发布版本并将其推送到PyPI。

   git tag -a 1.2.0 origin/main
   git push origin 1.2.0
   

2. 在以下渠道发布关于新版本的消息。运行dev/release_announcement.py脚本来生成帖子文本。

   • MozPhab在Mozilla Wiki上
   • Firefox工具公告在Discourse上