Flutter Framework Gardener 轮值手册:守护 flutter_flutter 主分支树健康(Tree Health)的完整守护流程

原创2026-10-14 19:42:201,966 阅读
文章标签:跨平台移动开发OpenHarmony图形学开发工具UI组件构建工具

Flutter Framework Gardener 轮值手册:守护 flutter_flutter 主分支树健康(Tree Health)的完整守护流程

导读

Framework Gardener(框架园丁)是 Flutter 框架仓库(本仓库为 CPF-Flutter 团队维护的 Flutter SDK 与 Engine 的 OpenHarmony 适配版本,即 Flutter-OH)中一个关键的角色轮值机制,其使命是消除框架、工具及相关团队在工程推进上的阻碍、解除上游自动滚动(autoroll)的阻塞、并尽可能缩短关键修复到达用户手中的延迟。本文以仓库内 Flutter-Framework-Gardener-Rotation.md 为核心骨架,系统讲解 Gardener 的职责边界、轮值安排、周期性树状态巡检流程,以及针对 devicelab 失败、LUCI 失败、Flaky 测试、引擎滚动失败、基准性能回退、Skia Gold 失败等场景的完整处置 SOP(Standard Operating Procedure),并补充本仓库 dev/devicelab、TESTOWNERS、.ci.yaml 等源码与配置层面的实现佐证。读完本文,你将掌握一套可直接复用的"树健康守护者"工作流:从发现树变红、定位失败分片、判断是否回滚,到上报基础设施工单的完整闭环。

一、Gardener 的角色定位:为什么需要"树园丁"

Flutter 是一个高度依赖持续集成与自动滚动的开源项目。在 flutter_flutter 这类仓库中,每天都有大量 PR 合入、上游依赖(Dart SDK、Skia、Clang、Fuchsia SDK 等)被机器人自动滚动进仓库,任何一次坏的合入都可能让主分支("树",Tree)变红,进而阻塞所有开发者的合入、阻塞 autoroller、甚至阻塞发版流程。

因此,仓库维护团队设置了 Framework Gardener 轮值制度,保证任何时刻都有明确的负责人(Point of Contact)来处理 flutter 仓库的问题,让工程师可以围绕"轮值期间生产力下降"这一预期来规划自己的工作。需要先说明的是:原文档明确指出,该角色当前使用的一些工具与沟通渠道仅对 Google 员工开放(如 Rotations 工具、部分日历与聊天频道),开放化改造的路线图参见文档开头提到的 On-call scheduling 文档。这意味着阅读本文的开发者应将这套流程视为流程设计参考与内部运维手册,而非可直接访问的公共工具链。

1.1 核心职责(Gardener 必须做)

原文档将 Gardener 的核心职责概括为三条:

  1. 让树保持绿色(Keep the framework tree green)——这是最高优先级,目的是让开发者、上游 autoroller 和发版流程不被阻塞;
  2. 确保他人知晓可能影响他们的所有问题——主动、及时地把状态与影响面同步给上游/下游相关方;
  3. 确保 bug 与调查任务被委派给正确的人并得到跟进——正确的人可以是别人,也可以是 Gardener 自己。

1.2 职责边界(Gardener 不必做)

文档同样明确了边界,避免轮值者被过度消耗:

  • 不包含非工作时间的工作。文档原文强调:"Tree redness does not trump work-life balance."(树的红色状态不得凌驾于工作与生活平衡之上)。贡献者可以在 Gardener 工作时间之外上报问题,但 Gardener 只需在下一个工作日响应即可;
  • 不要求亲自调查问题或修复 bug,除非真正合适的人选就是 Gardener 本人。

正是基于这样的职责设定,Gardener 应当利用自己的"徽章与帽子"(badge and hat,即被授予的轮值权限与身份)去:

  • 激进地回滚有问题的变更(Aggressively roll back problematic changes);
  • 把调查任务/问题委派给团队中正确的工程师并持续跟进;
  • 检测导致测试失败与 flakiness 的基础设施问题,并上报给基础设施团队;
  • 当引擎滚动(engine roll)导致树关闭时,通知 Engine Sheriff(引擎警长);
  • 主动向上游/下游沟通问题与状态。

这一"职责+边界"的设计,与本仓库 Tree-hygiene.md 中"回归应先回滚再提问,让树恢复绿色优先级更高"的原则一脉相承。

二、轮值管理(Rotation)

轮值安排由专用的 Rotations 工具管理,另有 Framework Gardener 日历可添加到个人日历中。文档注明:这两个链接当前均为 Google 内部资源。

轮值纪律上有三条约定:

  • 团队成员不应同时参与多个 Flutter 轮值。例如,参与引擎轮值(engine rotation)的成员自动豁免框架轮值,反之亦然;
  • 新成员根据所属团队加入单一轮值;
  • 休假前,或到岗后发现无法履行职责时,应提前查看后续轮值表,找一位志愿者与自己换班。在部分假期时段,如果大量成员休假、树上的活动又特别少,可以不安排专职 Gardener。

三、周期性巡检(Periodic scan):树的日常体检

Gardener 的核心日常工作始于打开 Framework build dashboard(构建仪表盘),并执行一套 10 步巡检流程。这套流程对"何时开始调查、何时开始升级"给出了明确判定规则,是整篇文档最可操作的骨架。

3.1 树状态颜色解读:先学会"读仪表盘"

在动手处理之前,必须先理解仪表盘上不同颜色方块的语义(这也是后续所有决策的前提):

状态 含义 Gardener 应采取的行动
黄色方块 + 感叹号 失败的测试正在自动重跑 树尚未完全关闭;可以开始调查,但建议等重跑完成后再升级
纯红色方块 / 红色方块 + 感叹号 重跑后仍失败,树已关闭 立即按下方 SOP 调查与升级
绿色方块 + 感叹号 曾失败、重跑后通过 可能是 flaky 测试或偶发基础设施问题,值得展开调查

3.2 十步巡检流程(Periodic scan 完整步骤)

原文档给出了完整的巡检清单,逐条如下:

  1. 若树已关闭,先识别哪些测试分片(test shards)在失败;
  2. 定位分片内具体失败的是哪个测试,尝试在日志中找到明显错误或失败原因。注意:这一步的处理方式会因失败发生在 devicelab(见 4.1 节)还是 LUCI(见 4.3 节)而不同;
  3. 在 Discord 的 tree-gardener 频道发布公告,说明树已变红、受影响的分片、以及日志中的失败信息;
  4. 将失败与具体提交交叉比对。如果显而易见是某个 PR 导致失败,立即回滚(见 4.4 节);
  5. 在 Flutter issues 中搜索已有的相同错误。某些 flake 并非特定测试套件独有,但仍是 flake,不应触发回滚;
  6. 如果失败发生在引擎滚动上,升级给 Engine Sheriff(见 4.6 节);
  7. 如果测试失败不是已知 flake 或基础设施问题,立即回滚(见 4.4 节);
  8. 升级给 test owner(测试负责人);
  9. 树重新开放后,在 Discord 的 tree-gardener 频道宣布;
  10. 若树是开放的,调查绿色感叹号方块(重跑后通过的测试),它们可能是 flaky 或偶发基础设施问题(见 4.5 节);同时检查基准性能回退(见 4.7 节),必要时提交 issue 并升级。

此外,文档要求 Gardener 取消 Discord 上 tree-gardener 频道和 hackers-infra 频道的静音——贡献者会被鼓励直接向你上报树的关闭情况,你需要尽可能快地在那里响应。如果希望收到树变红的自动通知,还可以取消 tree-status 频道的静音。

3.3 巡检流程背后的基础设施:从源码看"分片与仪表盘"

这套巡检流程依赖的测试基础设施在本仓库中均有对应实现:

  • 测试分片定义:仓库根目录的 .ci.yaml 定义了所有 CI 目标(target)与平台属性。例如 linux_android_emu 平台属性配置了 Android SDK 版本(如 version:36v1)、AVD 镜像(android_36_google_apis_x64.textpb)、OpenJDK 21 与 KVM 等依赖;每个 target 通过 shard 键决定运行哪个分片;
  • 树状态检查:关于 PR 上 "tree-status" 检查的语义(它不是检查你的 PR,而是反映主分支当前是否通过测试),参见 Fix-failing-checks.md;
  • 失败日志定位:通过 flutter-dashboard 的 "View more details" 页面拿到完整测试输出,通常会出现 EXCEPTION CAUGHT BY FLUTTER TEST FRAMEWORK 形式的失败栈,据此定位失败测试并在本地复现(复现方法见下文 4.1 节与 devicelab README)。

四、各类失败的处理 SOP

4.1 处理 devicelab 失败(Handling a devicelab failure)

DeviceLab 是 Flutter 在真实物理设备上跑测试的实验室(dev/devicelab/README.md 对其运行机制有完整说明:任务失败会自动重跑,若最后一次重跑成功则记为成功并标记 flake;若全部重跑失败则上报失败且不收集性能指标)。处理 devicelab 失败的标准动作:

  1. 若 devicelab 方块(Android、Apple 或 Windows 图标)为红色或黄色,点击该方块并点击 "Download All Logs"(下载全部日志)。注意:由于失败后会自动重跑以检测 flake,这些日志可能包含多次测试运行的输出;
  2. 如果许多不同测试在同一台 agent 上同时失败,这很可能是基础设施故障的信号——必要时提交基础设施工单(见第五节);
  3. 注意手机偶尔需要手动重启。发生这种情况时,在 Discord 的 hackers-infra 频道升级并提交基础设施工单。

本地复现与验证:Gardener 判断"是否真的坏了"时可以借助 devicelab 的本地运行能力。在 dev/devicelab 目录下:

# 运行单个任务(任务名为 bin/tasks 下文件的 basename,如 complex_layout__start_up)
../../bin/cache/dart-sdk/bin/dart bin/test_runner.dart test -t {NAME_OF_TEST}

# 关闭自动重试(默认失败会自动重试 2 次)
../../bin/cache/dart-sdk/bin/dart bin/test_runner.dart test --exit -t {NAME_OF_TEST}

任务入口由 dev/devicelab/bin/test_runner.dart 提供,它通过 CommandRunner 注册了 test 与 upload_metrics 两个子命令。需要说明的是,本地运行会真实改动你的环境(自动启停 Gradle、达到阈值后自动重启连接的 Android/iOS 设备等),应在专用测试机上执行。

4.2 处理 Firebase Test Lab 失败(Handling a Firebase Test Lab failure)

Firebase 测试实验室中的设备不由 Flutter infra 团队管理,因此处理方式与自有设备不同:

  1. LUCI 日志通常会列出测试失败的设备。在日志中查找 Firebase 链接,其中包含失败设备的日志;
  2. 如果日志中描述的失败与最近的提交无关,联系 omnilab-ftl-flutter 组;
  3. 或者,查看 LUCI 日志中关于如何通过 Slack 通知 Firebase 的说明。

4.3 处理 LUCI 失败(Handling a LUCI failure)

LUCI(Layered Universal Continuous Integration,Chromium 的 CI 系统)失败的处理非常直接:

  1. 若 Chrome 图标(LUCI)方块为红色,点击红色方块并选择 "Open Log for Build #1234" 查看 LUCI 中失败的具体测试;
  2. 必要时提交基础设施工单。

LUCI 构建失败的深入解读(如何定位测试步骤、查看 stdout、区分 flake 与 infra 错误)可参见 Reducing-Test-Flakiness.md 与 Fix-failing-checks.md。

4.4 回滚提交(Reverting commits):树守护者的第一武器

判定原则:如果测试失败不是已知 flake 或基础设施问题,立即回滚。这与仓库 Tree-hygiene.md 的"先回滚、后提问"原则完全一致——回滚没有羞耻可言,它是工程常态。

情况一:提交在 24 小时内落地(可自动回滚)

  1. 找到引发问题的补丁 PR,加上 Revert 标签;
  2. 仓库基础设施会自动创建 revert PR 并合入。

情况二:无法自动回滚(手动创建 revert PR)

  1. 在坏掉的已合并 PR 底部通过 "Revert" 按钮创建 revert PR;
  2. 给 PR 加上 revert 标签,允许机器人无需批准即可合入;
  3. 把原作者加为 reviewer 以便其收到通知;如果原作者不是 flutter-hackers 成员,还需要加上原 PR 的评审者;
  4. 在 "Related Issues" 中添加描述该失败的相关 GitHub issue 链接;
  5. 在 Discord 的 tree-gardener 频道 @ 原作者并附上 revert PR 链接;若对方不可用则发邮件;若对方既不是 Flutter committer 也不在 Discord 上,升级给原 PR 的评审者;
  6. 只要 analyze-linux 测试通过即可合并——不需要等所有 presubmit 测试通过,也不需要一个 LGTM;
  7. 重新打开被原提交自动关闭的任何 issue,并添加评论:"This has been reverted with pull request #1234."

补充一个与回滚直接相关的仓库内原则:根据 Tree-hygiene.md,revert 时 commit message 只允许出现一次 "Revert",且只有当你确实把仓库恢复到已知良好状态时才使用 "Revert" 字样;也不要用 "Reland"——重新落地时应以原始 commit message 重新合入,并附上原 PR 与 revert PR 的链接,方便后人追溯。

4.5 处理 Flaky 测试(Handling a flaky test)

Flake 对生产力的杀伤力极大——它会静默触发 Gardener 本要预防的所有关键问题(红色树状态)。因此,flake 应按可复现的破坏一样对待,即当作"它一直在失败"来处理。

遇到疑似 flake 的失败时:

  1. 重新触发测试;
  2. 如果构建"没有失败"(即重跑"通过"),它就是一个 flake,应按失败测试对待;
  3. 按照本文指南查找或创建新的 GitHub issue;
  4. 如果该测试既不是最近引入、也不是最近修改,禁用(disable)该测试——测试负责人会在调查中将其重新打开或删除。

在仓库源码层面,这类"临时跳过"的测试在 Tree-hygiene.md 中有规范约定:必须使用 skip 参数并在同一行注释附上跟踪 issue 链接(如 skip: true, // https://github.com/flutter/flutter/issues/XXXXX),且跟踪 issue 需要打上 skip-test 标签;否则 analyze 脚本会报错并导致检查失败。

4.6 处理引擎滚动失败(Handling an engine roll failure)

如果失败发生在引擎滚动上(即引擎新版本通过 Autorollers 机制滚入框架仓库后导致树关闭):

  1. 联系 Engine Sheriff 聊天频道,让引擎警长定位并回滚引发问题的引擎或上游提交;
  2. 在处理期间,与引擎警长协调暂停与恢复 "Engine to Framework" 自动滚动器。

仓库内 Autorollers.md 解释了自动滚动的运作方式:各依赖(Clang、Fuchsia SDK、Skia、Dart SDK 等)由机器人自动更新,通过修改仓库根目录的 DEPS 中的版本行(如 skia_revision)实现;而 Flutter Pub Roller 则通过本仓库 dev/packages_autoroller 中的脚本,在每个框架提交合入后自动保持 pub 依赖最新。理解这些滚动器的机制,有助于 Gardener 快速判断"失败是否来自滚动提交"。

4.7 处理基准性能回退(Handling a benchmark regression)

Gardener 需要同时盯住两个性能看板:

  • framework benchmarks(框架基准)——检查回归并提交 issue、升级;
  • engine benchmarks(引擎基准)——在左侧选择 Triage 项,逐条走查新出现的 issue。每个导致回归的提交,其对应列中会出现标记,指示该提交处的指标是低(low)还是高(high)。

查看数据:点击标记会弹出该提交附近近期数据的曲线图。从这里可以:

  1. 选择 View Dashboard 查看该提交周边的长期趋势(在仪表盘中可用 WASD 键缩放);
  2. 点击提交本身,获取可跳转到该提交的链接。

确认为新回归(非噪声)时:

  1. 在 GitHub 上新建 issue;
  2. 打上 team: benchmark 与 severe:regression 标签;如果是性能类基准,再加 severe:performance 标签;
  3. 将 skia-perf 中的性能图链接("permalink")粘贴进 bug,方便他人看到你所看到的情况;
  4. 确定回归开始的 CL(变更列表),尽可能标注可能是问题源的代码库区域与提交者;
  5. 尝试确定应接收该 issue 的团队(可疑的滚动通常是线索);
  6. 分配初始优先级:
    • 保留 P0 给显著高于基线(1.5 倍或更多)的回归,或出现规律性尖峰、暗示设备实验室可能存在问题的情形;
    • 保留 P2 给出现**缓慢爬升(slow creep)**的 issue;
  7. 在 skia-perf 中你处理该回归的评论里记下 bug ID 并拒绝(reject)该基准(点击 X);
  8. 在 Discord 上通知你识别出回归的目标团队并附上链接——确保 @ 某个人(最好是该团队 TL)以保证被注意到;
  9. 将你提交的 issue 同时通知给 Flutter 引擎警长和 Flutter Hackers Discord 频道。

如果只是噪声:在 triage 详情弹窗中勾选复选框接受(accept)该基准即可。

4.8 处理 Skia Gold 失败(Handling a Skia gold failure)

Skia Gold 是 golden 文件(基准图片)的管理系统。若树因 golden 测试失败而关闭,请参见仓库内的 golden test build breakage 指南。该指南说明了此类失败的典型成因(图片变更未经 triage 就合入,导致 post-submit 出现 Skia Gold received an unapproved image in post-submit testing 错误)以及处理方式(到 Flutter Gold 仪表盘查看图片批次:是预期变更则点勾批准并重跑测试,非预期则回滚相关变更)。

五、升级(Escalation)与基础设施工单

5.1 升级标准动作

当确定需要升级时:

  1. 升级给 test owner(测试负责人),若尚无公开 issue 则新建 GitHub issue:
    • 标题必须包含失败的测试名;
    • 将 issue 指派给测试负责人,优先级 P1;
    • 添加 c: contributor-productivity 标签;
    • 包含失败测试的链接;同时下载相关日志并作为附件上传——即使失败链接已含相同信息也必须这样做,防止日志被清理后 issue 变成"死链接";
  2. 在 Discord 的 tree-gardener 频道 @ 提及测试负责人并附上 GitHub issue 链接;若其不可用,升级给其他团队成员;持续升级直到有人确认正在调查该 issue。

"test owner"如何确定?仓库根目录的 TESTOWNERS 文件就是答案:它以"路径 + @handle + @团队"的格式建立了测试到负责人的映射,例如 /dev/devicelab/bin/tasks/analyzer_benchmark.dart @bkonyi @flutter/tool、/dev/devicelab/bin/tasks/slider_perf_android.dart @tahatesser @flutter/framework。新 flaky bug 上报时,该文件会被用作参考,默认给对应 TL 指派并给子团队打标签,便于后续 triage。

5.2 提交基础设施工单(Filing an infra ticket)

  1. 打开 new infra issue 模板;
  2. 填写描述性标题。文档举例:"Add a LUCI builder for linux web engine"或"Debug gallery startup"远好于"quick request"或"test doesn't work?";
  3. 在描述中清晰描述问题或请求。例如,若请求在机器人上运行若干命令,应说明:为什么需要、需要哪些命令、在哪些机器人上执行、如何验证结果;
  4. 添加 team-infra 标签和优先级标签:
优先级 含义 处置要求
P0(immediate) 构建破坏或回归 尽可能快地修复,先于其他任何工作;应非常罕见,仅在关键工作无 workaround 被阻塞时使用;理想情况下找到 workaround 后立即降级为 P1
P1(high) 用户受影响但未被阻塞;或若不处理将发生即时级事故(如配额将耗尽) 当天(8 个工作小时内)修复;服务降级(构建机器人可用但启动缓慢)、时间敏感请求也适用;应相对罕见
  1. 点击创建即可,无需设置 assignee——所有新工单由 infra oncall 统一处理。

六、沟通渠道(Communication channels)

文档将沟通渠道分为公开与 Google 内部两类,Gardener 的大部分沟通发生在 Discord 上:

公开渠道:

  • 树关闭的升级与公告:tree-gardener 频道;
  • 机器人自动发布的树红/绿状态:tree-status 频道;
  • 基础设施问题:hackers-infra 频道;
  • 基础设施工单:通过上述 new infra issue 模板提交。

Google 内部渠道:

  • 引擎问题:Flutter Engine Sheriff 聊天(频道名带当前当值者用户名);
  • LUCI 帮助:LUCI Users 聊天。

文档在 References 中还列出了 [Flutter Engine Sheriff Playbook](Google 内部)与 [On-call scheduling for Flutter] 作为延伸阅读。注意:这些链接中除仓库内文档外均为外部或 Google 内部资源,公开社区读者无法直接访问,可将其视为流程背景信息。

七、在 Flutter-OH(本仓库)中的落地观察

最后,结合本仓库(CPF-Flutter 团队维护的 OpenHarmony 适配版本)的实际情况做一些说明,帮助读者将上述通用轮值流程映射到本仓库:

  • 测试基础设施完整保留:本仓库保留了上游的 dev/devicelab(含 bin/tasks 任务集、lib/framework/task_result.dart 中的 TaskResult.success / TaskResult.failure / benchmarkScoreKeys 等结果模型)、根目录 TESTOWNERS、.ci.yaml 与 docs/contributing/testing 全套文档,因此上述巡检、回滚、升级流程在本仓库的工程实践中具备同样的参考价值;
  • OH 平台任务扩展:从 dev/devicelab/bin/tasks 的源码结构可以看到,任务集在 OH 适配分支上增加了大量 _ohos 后缀的基准任务(如 animated_advanced_blend_perf_ohos__timeline_summary.dart、backdrop_filter_perf_ohos__timeline_summary.dart 等),说明 devicelab 体系被扩展到了 OpenHarmony 设备的性能与功能测试上——这也意味着 Gardener 在巡检本仓库时需要额外关注 OH 分片的失败与回归;
  • CI 入口的 OH 化:本仓库的 ci/test.sh 通过 python3 runner.py test 驱动测试门禁(依赖 Python3 与 PyYAML),ci/ohos_ci_runner.sh 提供了 OH 的 CI 运行入口,与上游 dev/bots/test.dart 的分片机制形成对照;
  • 合入门禁差异:本仓库的合入流程见 Flutter-OH-Contributor-PR.md,采用评论 start build 触发流水线门禁(DCO 检查、编译检查、静态检查),评审/审查通过后由 openharmony_ci 自动合入——这与上游"加 autosubmit 标签由机器人合入"的机制不同,Gardener 或维护者在处理回滚与合入时需注意这套 OH 门禁规则(例如回滚 PR 同样需要 DCO 签名与门禁通过)。

参考文档索引

登录后查看全文
flutter_flutter