OpenConsole 代码提交全解：dev 分支模型、inbox 中转与 Git2Git 同步机制

本文以 doc/submitting_code.md 为核心，完整讲解 Windows 控制台（OpenConsole）仓库的分支模型、代码从公开仓库回流操作系统仓库（OS repo）的提交流程，以及 cherry-pick 失败时的手动处理步骤。读完后你将掌握 dev/main、dev/<alias>/xxx 与 inbox 三类分支的分工，理解 Git2Git 自动复制提交并生成 OS 仓库 PR 的机制，并能在 VSTS 拒绝 cherry-pick 时按标准流程手动完成同步。

分支模型：dev/main、dev/ 前缀与 inbox

OpenConsole 仓库的分支体系由三种角色构成，理解它们是理解整个提交流程的前提。

dev/main：主分支

dev/main 是仓库的主分支（primary branch），所有经过评审的代码最终都合并到这里。

dev/ 前缀：CI 自动构建与测试的触发条件

任何以 dev/ 开头的分支都会被 CI 系统识别，并自动执行 x86 与 amd64 两种架构的构建，同时运行单元测试（unit tests）和功能测试（feature tests）。功能分支（feature branch）的命名约定为：

dev/<alias>/<whatever you want here>

例如 dev/austdi/SomeCoolUnicodeFeature。其中 dev 前缀和你的 alias（个人代号）是命名中的关键部分。

这一约定与仓库中的测试基础设施是吻合的。CI 跑的"unit 和 feature tests"正是仓库 tools/ 目录下的两组脚本所驱动的内容：

• tools/runut.cmd：通过 TAEF 的 te.exe 运行 Conhost.Unit.Tests.dll、ConParser.Unit.Tests.dll、ConAdapter.Unit.Tests.dll、Types.Unit.Tests.dll 等十余个单元测试 DLL；
• tools/runft.cmd：运行 ConHost.Feature.Tests.dll 功能测试。

测试框架与运行方式的细节可进一步参考 doc/TAEF.md 与 doc/building.md。

inbox：对接 OS 仓库的中转分支

inbox 是一个特殊分支，用于协调 OpenConsole 代码进入主操作系统仓库。代码最终会落在 OS 仓库的 /onecore/windows/core/console/open 目录下。文档特别提示：提交改动前，最好确认该目录在 razzle（本地构建环境）下可以正常构建——即本地验证与 OS 侧构建环境保持一致。

代码提交流程：从 dev/main 到 OS 仓库

因为 OpenConsole 在 OS 仓库之外构建，代码一旦合并进 dev/main，还需要一套机制把它带回 OS 仓库。完整流程如下：

1. 合并 PR 到 dev/main：社区/团队的 PR 经过评审后合并（最好以 squash 方式压成一个提交）；
2. cherry-pick 到 inbox：将该 PR 的提交 cherry-pick 到一个指向 inbox 分支的新 PR 中；你可以自行审批并完成（complete）这个 inbox PR；
3. Git2Git 自动复制：仓库中有一个名为 Git2Git 的工具，它会监听 inbox 上的新合并，并把提交复制（replicate）到 OS 仓库；
4. OS 仓库自动生成 PR：inbox PR 提交后大约一分钟，Git2Git 会以 miniksa 这个别名在 OS 仓库中创建一个 PR，并自动指向当前正在使用的 OS 分支，需要你手动审批并完成合并；
5. 构建验证：OS 仓库合并完成后，建议立即用新代码构建一次 OS 分支，确保这个 PR 不会成为当晚构建流水线（build break）的元凶。

哪些文件会同步到 OS 仓库：Git2Git 过滤器

从源码结构看，并非整个 OpenConsole 仓库都会被复制进 OS 仓库——Windows Terminal 的 XAML/C++/WinRT UI 部分、示例代码、scratch 实验目录等都不属于 OS 组件。这一点可以从 consolegit2gitfilters.json 得到印证：该文件定义了 Git2Git 的排除过滤器，例如 ContainsFilters 中列出了 /src/cascadia/（Windows Terminal UI 工程）、/src/winconpty/、/scratch/、/samples/、/doc/ 等目录，SuffixFilters 中排除了 .vcxproj、.log、.db 等文件类型。换言之，同步到 OS 仓库的核心是 src/host、src/server、src/renderer、src/terminal 等控制台核心组件的源码，而非整个 GitHub 仓库的镜像。

提交日志的整理：Get-OSSConhostLog.ps1

与 Git2Git 流程配套的还有一份 PowerShell 脚本 tools/Get-OSSConhostLog.ps1。从该脚本的注释（L9-L12）可以看到两个与 Git2Git 直接相关的约定：

• 脚本按提交区间生成提交日志，并过滤掉 Git2Git 排除清单中的文件变更（过滤规则即来自 consolegit2gitfilters.json）；
• 会把提交信息中的 GitHub issue 编号改写为 GH-XXX 前缀形式，"以免让 Git2Git 或 Azure DevOps 混淆"；社区贡献（提交者邮箱非 @microsoft.com）则会标记为 CC- 前缀，便于后续识别。

这也解释了为什么同步工具对提交信息的格式敏感——在 dev/main 上合并时保持提交信息干净（这也是"preferably squashed"建议的另一个原因）。

cherry-pick 到 inbox 失败时的手动流程

文档明确写道：有时 VSTS 就是不允许把提交 cherry-pick 到 inbox 分支——"它可能有正当理由，也可能只是脾气古怪（finicky）"。此时需要在本机手动完成合并，步骤如下：

1. 确保已拉取 dev/main 和 inbox 分支的最新提交；
2. 从 inbox 创建一个新分支；
3. 把 PR 中的提交 cherry-pick 到这个新分支上（如果当初合并进 dev/main 时已经 squash 过提交，这一步会更容易）；
4. 解决所有合并冲突并提交；
5. 把新分支推送到远端；
6. 以该分支对 inbox 发起新的 PR；
7. 完成该 PR，然后继续完成 OS 仓库中自动创建的那个 PR（回到上一节的第 4、5 步）。

提交前的本地验证环境：razzle

无论走自动 cherry-pick 还是手动流程，"确认改动在 OS 侧目录可构建"都是提交前的硬要求。仓库提供了一整套模拟 OS 开发者环境的脚本：

• tools/razzle.cmd：一键搭建开发环境。它会把 tools 目录加入 PATH、设置 OPENCON/OPENCON_TOOLS/OPENCON_TOOLS 相关环境变量（OPENCON 即仓库根目录，见 L16-L18 的路径推导）、把 NuGet 包目录加入 PATH 并执行 nuget restore、通过 vswhere 在 [17.0,19.0) 版本区间内查找 MSBuild（兼容 VS 2022 17.x 与 VS 18 的预发布版本），并定位 TAEF 的 te.exe（L133）。脚本支持 dbg、rel、x86 参数来覆盖默认配置（默认 Debug、架构随 PROCESSOR_ARCHITECTURE 自动判定为 x64 或 x86）；
• 构建命令：bcz（清理并构建整个解决方案）、bx（只构建当前目录下的项目，等价于 bcz exclusive no_clean，见 tools/bx.cmd）；
• 测试命令：runut（单元测试）、runft（功能测试）、runuia（UIA 测试）。

对应的 PowerShell 用法见 doc/building.md：Import-Module .\tools\OpenConsole.psm1 后使用 Set-MsBuildDevEnvironment、Invoke-OpenConsoleBuild、Invoke-OpenConsoleTests。首次构建前记得执行 git submodule update --init --recursive 恢复子模块依赖。

从 razzle.cmd 的注释（L5-L7）可以看出这些脚本的意图："重现真正的 Windows 开发者体验"——因为它们要模拟的正是 OS 仓库内构建 open 目录的环境，这与"提交前用 razzle 验证目录可构建"的要求是一体的。

附注：社区贡献路径与本文流程的区别

需要说明适用前提：本文描述的 dev/main → inbox → OS 仓库流程，是操作系统组件（in-box console）代码回流内部 OS 仓库的提交流程，面向参与 in-box 组件开发的成员。而普通社区贡献者向 Windows Terminal 提交代码走的是另一条公开路径：fork、建分支、提 Draft PR、公开评审后合并，详见 CONTRIBUTING.md（其中同样提醒：你的改动可能同时影响 Windows Terminal 和 Windows Console，并最终被重新纳入 Windows 本身，因此社区 PR 会获得与官方提交同等严格的审视）。两条路径的交汇点正是本文主题——OS 仓库中的 console 代码持续来源于这个公开仓库，同步机制就是 Git2Git + inbox 分支。

小结

分支	角色	触发/结果
dev/main	主分支	所有 PR 的最终合并目标，建议 squash 合并
dev/<alias>/xxx	功能分支	CI 自动执行 x86/amd64 构建 + 单元/功能测试
inbox	OS 仓库中转分支	Git2Git 监听其合并，约 1 分钟后以 miniksa 别名在 OS 仓库（/onecore/windows/core/console/open）创建 PR

流程要点可以浓缩为一句话：先在 dev/<alias>/xxx 上开发并让 CI 全绿，squash 合并进 dev/main，再 cherry-pick 到 inbox，等待 Git2Git 在 OS 仓库生成 PR 并完成审批，最后构建 OS 分支确认无回归；cherry-pick 被拒时按 7 步手动流程在本地完成。 过滤规则（consolegit2gitfilters.json）与日志整理脚本（tools/Get-OSSConhostLog.ps1）则保证了只有 OS 组件相关的、提交信息规范的代码才进入操作系统仓库。