Windows Terminal（OpenConsole）开源贡献指南：从提 Issue、写 Spec 到 PR 合并的完整实践

本文基于 OpenConsole 仓库（Windows Terminal 与 Windows 控制台主机 conhost 的源码仓库）的 CONTRIBUTING.md 贡献者指南展开，完整覆盖其“开放开发流程、机器人自动维护、Issue 提交规范、Spec 设计、Fork/分支/构建/测试、代码评审与合并”的全部核心内容，并结合仓库中的真实 Issue/PR 模板、构建脚本与 TAEF 测试文档补充可复制的操作细节，帮助开发者走完一次符合项目质量标准的社区贡献全流程。

一、开放开发模式：团队与社区共用同一套流程

CONTRIBUTING.md 开篇强调：Windows Terminal 团队在仓库中“公开开发”（Open Development）——自己发现的 Bug 直接提 issue，新想法直接提 feature request，在分支上开发、在公开的 PR 评审中讨论（包括所有好的、坏的、难堪的部分）。这样做的目的是保证团队以与社区相同的流程和质控标准约束自己，同时把团队文化中的“部落知识”暴露给新人，让人能理解“为什么代码/功能是这样的”。

对贡献者最重要的推论是：社区 PR 会按提交进官方 Windows 源码的标准被严格评审。CONTRIBUTING.md 明确警告：你的改动可能同时影响 Windows Terminal 和 Windows Console，最终可能被重新并回 Windows 本体，因此社区 PR 与团队成员、合作方提交给 Windows 官方源码的 commit 受到同等力度的审查。

仓库机器人：标签驱动的工作流

团队每周数次对 issue 进行分诊（triage），并部署了一个 bot 引擎来自动化常见流程。bot 的具体规则见 doc/bot.md，其核心机制包括：

• 新 issue 自动标记 Needs-Triage，由核心贡献者团队在分诊会上打上 Product-、Area-、Issue- 分类标签，Resolution- 标签用于已关闭项；
• 需要作者补充信息时打上 Needs-Author-Feedback；作者若有回应，标签自动移除并转为 Needs-Attention 提醒团队；若 4 天无活动则追加 No-Recent-Activity，再持续 3 天无响应则作为 stale 自动关闭；
• PR 被评审者要求修改时自动打 Needs-Author-Feedback，7 天无活动标 No-Recent-Activity，再 7 天仍无活动则自动关闭 PR；
• AutoMerge 标签触发自动合并：状态检查全部通过后等待至少 480 分钟，以 Squash 方式合并并尝试删除分支；若合并前又被人推送了变更（无写权限者），标签会被自动移除。

因此 CONTRIBUTING.md 给贡献者的直接要求是：提交 issue 或 PR 后保持关注 GitHub 通知，若长期不回应信息请求，issue/PR 可能被机器人自动关闭。

二、安全问题：不要走公开的 GitHub issue

CONTRIBUTING.md 明确要求：安全漏洞不要通过公开 GitHub issue 报告，应通过 SECURITY.md 所述渠道报告给 Microsoft Security Response Center（MSRC）。SECURITY.md 列出了报告时应尽量提供的信息清单：

• 问题类型（如缓冲区溢出、SQL 注入、跨站脚本等）；
• 相关源文件的完整路径；
• 受影响源码的位置（tag/branch/commit 或 URL）；
• 复现所需的特殊配置；
• 逐步复现说明；
• PoC 或漏洞利用代码（如可能）；
• 问题影响及攻击者可能的利用方式。

仓库的 issue 模板配置 config.yml 也印证了这一点：该模板关闭了空白 issue（blank_issues_enabled: false），并将安全报告导向 MSRC、把文档类问题分流到文档仓库，普通用户无法随意建立无模板的 issue。

三、开始工作之前：先提 Issue，再动手

CONTRIBUTING.md 用一条“简单规则”作为所有贡献的前置条件：

如果你有疑问、发现疑似问题、想提议新功能等，请先搜索/建立 issue，再开始修复/实现工作。

先搜索已有 issue

项目进展很快，同样的问题很可能已被他人发现甚至修复。提交新 issue 前，应先搜索已打开和已关闭的 issue。若已有 issue 描述了你的问题，直接点赞（upvote）并补充复现步骤、环境信息等，而不是重复开单。

什么情况都该提 issue

文档列出了应当提 issue 的全部典型场景：

• 分不清是在报 bug 还是请求功能 —— 提 issue；
• 文档/视频里没找到答案的问题 —— 提 issue；
• 想知道某功能是否在规划中 —— 提 issue；
• 有全新功能创意 —— 提 issue/请求/想法；
• 不理解如何完成某事 —— 提 issue。

点击 “New Issue” 时，项目提供多类模板供选择（Bug 报告、功能请求等），对应仓库中的 Bug_Report.yml 与 Feature_Request.yml：

完整填写模板：文档要求的实战信息清单

CONTRIBUTING.md 强调尽量提供尽可能多的信息，并给出具体清单：

• 设备信息（CPU 类型、内存、磁盘等）；

• Windows 构建版本，文档给出了三种获取方式：

  PowerShell Core（pwsh）：

  C:\> $PSVersionTable.OS
  Microsoft Windows 10.0.18909
  

  Windows PowerShell：

  C:\> $PSVersionTable.BuildVersion
  
  Major  Minor  Build  Revision
  -----  -----  -----  --------
  10     0      18912  1001
  

  或在 Cmd 中：

  C:\> ver
  
  Microsoft Windows [Version 10.0.18900.1001]
  

• 使用的工具与应用（如 VS 2022、VSCode 等）；

• 不要假定维护者熟悉你所在的环境，也不要假定他们熟悉你所用的发行版/工具——“教会我们如何帮你”；

• 尽可能详细的复现步骤——文档直言“你能写出来的细节，可能刚刚够用”；

• 若是某字符/字形渲染错误，请给出具体 Unicode 码点（如 U+1F4AF、U+4382）；

• 优先提供错误文本；无法抓取文本时再截图；

• 命令行输出优先贴文本脚本而非截图；

• 如果你打算自己实现修复/功能，务必说明；否则会被默认由团队负责，或被标为 Help-Wanted。

对照仓库实际的 Bug_Report.yml 模板，上述要求被具体落实为字段：Terminal 版本号（可从“关于”对话框获取）、Windows 构建号（提示运行 ver 或 [Environment]::OSVersion）、其他相关软件及版本、复现步骤（必填）、预期行为、实际行为（必填）等；崩溃类问题还要求提供 Feedback Hub 提交链接以便在后端找到诊断数据。功能请求模板 Feature_Request.yml 则要求描述新功能解决的问题（必填）与可选的技术实现设想，并自动打上 Issue-Feature 标签。

不要发 “+1” 评论

CONTRIBUTING.md 特别警告：不要发 “+1”“me too” 之类评论，它们只会增加噪音。想表示同样受影响，应点击 issue 上的表情按钮点 👍，这样团队才能真实度量一个问题的影响面。

四、贡献修复与功能：选对 Issue 分类

CONTRIBUTING.md 指出新贡献者的最佳入口是团队维护的 “walkthroughs”（为特定 issue 写好的入门小指南，通常是适合首次贡献的 issue）和 good first issue 标签的 issue；熟悉代码库后可直接挑 Help-Wanted 标签的 issue 或任何感兴趣的 issue。项目沿袭内部工作跟踪体系，将 issue 分为三类：

• Issue-Bug：已有代码支持某场景但没做对，修复路径是调试坏掉的功能并改正错误代码；
• Issue-Task：尚未实现的小块新功能，通常是单个原子 PR 可完成、不需要太多设计讨论（或所属大功能已有 spec）的工作；
• Issue-Feature：较大的新能力，往往需要讨论实现方式、引入复杂的新设置，或由许多 task 组成，通常要求先写 spec（见下节）。

文档说明 Bug 和 Task 最容易上手，但不必害怕 Feature——已有社区成员贡献过相当有分量的 feature 级工作（伴随大量讨论）。

关于指派：团队倾向于把 issue 指派给该领域负责人。这不代表社区不能参与——应与被指派人沟通确认能否接手；若一个 issue 的指派已超过一个月，通常可以自行认领尝试。

何时需要写 Spec

• 若 issue/功能简单明了，与团队成员对齐方案后即可直接进入开发阶段，小问题会标 Issue-Bug 或 Issue-Task；
• 需要认真思考与正式设计的问题会标 Issue-Feature，并要求先写 spec，且常被加入团队的 “Specification Tracker” 项目跟踪。

Spec 的价值在于：让协作者在写代码之前讨论不同解法、描述功能行为、功能对用户的影响、失败时的行为等；在 spec 上达成一致，往往换来更简单的代码和更少的浪费。

编写/参与 Spec 的规范

• Spec 按与代码贡献相同的方式管理：fork、分支、通过 PR 提交；
• 以 Markdown 编写，存放在 doc/specs 目录下，命名为 [issue id] - [spec description].md；
• 必须遵循 spec 模板并填写要求的字段。spec-template.md 要求 front-matter 中提供作者、创建/更新日期、关联的 issue id，正文至少包含 Abstract（概述）、Inspiration（动机）、Solution Design（方案设计，可含 ASCII 图）、UI/UX Design（对终端用户的可见影响），以及 Capabilities 小节，逐项论证变更对 Accessibility（辅助功能）、Security（安全性）、Reliability（可靠性）等关键维度的影响。

doc/specs 目录中已有大量按此规范落地的真实 spec，例如 Keybinding Arguments、Command Palette、[Search spec](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/?utm_source=gitcode_repo_files#1564 - Settings UI/spec.md) 等，可作为写作参照。团队成员乐于帮助评审并推动 spec 完成。

Help Wanted 机制

团队批准某个 issue/spec 后开发即可开始。若暂无开发者接手，spec 会被“停放”等待，其 issue 打上 Help-Wanted 标签。按文档说明，机器人还会处理一种冲突：当某 issue 已有新 PR 建立时会被打上 In-PR 标签，同时自动移除 Help-Wanted，避免有人在已有人提交修复的 issue 上重复劳动（见 doc/bot.md 的 “Remove Help Wanted from In PR issues” 规则）。

五、开发实操：Fork、分支、构建

与团队成员对齐方案（或 spec 获批）后的开发流程为：

1. 如未 fork，先 fork 仓库；
2. 本地 clone 自己的 fork；
3. 创建并推送特性分支；
4. 创建 Draft Pull Request（草稿 PR）；
5. 在分支上开发；
6. 构建并验证可用，遇到问题参考构建指南。

结合仓库文档，具体命令如下（均出自 doc/building.md 与 README.md）：

前置环境（README 列出的前提）：Windows 10 2004（build ≥ 10.0.19041）或更新；Windows 设置中开启开发者模式；PowerShell 7+；Windows 11 (10.0.26100) SDK（10.0.26100.8249+）；VS 2026 18.6+ 及 “Desktop Development with C++”“WinUI application development” 工作负载；构建测试工程还需 .NET Framework 4.7.2 Targeting Pack。仓库提供了 winget 配置文件（winget configure .config\configuration.winget）一键安装环境。

子模块初始化（OpenConsole 使用 git submodules 管理部分依赖）：

git submodule update --init --recursive

PowerShell 构建：

Import-Module .\tools\OpenConsole.psm1
Set-MsBuildDevEnvironment
Invoke-OpenConsoleBuild

tools/OpenConsole.psm1 还导出：Invoke-OpenConsoleTests（跑测试，默认跑单元测试）、Start-OpenConsole（启动输出目录里的 OpenConsole.exe，默认 x64）、Debug-OpenConsole（启动并附加默认调试器）、Invoke-CodeFormat（clang-format 格式化全部 C++ 文件以匹配项目风格）。

Cmd 构建：

.\tools\razzle.cmd
bcz

配套测试脚本：runut.cmd（单元测试）、runft.cmd（功能测试）、runuia.cmd（UIA 测试）、runformat（clang-format）。

构建配置类型有三种：Debug、Release、AuditMode；其中 AuditMode 是启用 CppCoreCheck 额外静态分析的分析模式。NuGet 依赖版本统一由 dep/nuget/packages.config 定义，导入语句集中在 src/common.nugetversions.props 与 src/common.nugetversions.targets；升级版本时需三处同步修改。

注意：不能直接运行 WindowsTerminal.exe 启动 Terminal，需通过构建/部署 CascadiaPackage 项目（CascadiaPackage.wapproj 会产出 .msix，VS 中需将该项目 Debug 页的 “Application process” 和 “Background task process” 都设为 “Native Only” 后按 F5 调试）。命令行构建包的完整命令见 doc/building.md。

六、测试：TAEF 框架

CONTRIBUTING.md 将测试列为开发工作流的关键组成：Windows Terminal 与 Windows Console 都以 TAEF（Test Authoring and Execution Framework，微软内部用于统一测试系统、驱动与应用代码的测试框架）作为主测试框架。若改动影响既有测试或开发新功能，需按 doc/TAEF.md 在本地验证：

• TAEF 运行器 te.exe 随 Microsoft.Taef NuGet 包提供；在普通 CMD 中需先执行 .\tools\razzle.cmd 初始化环境，之后可用 %TAEF% 别名指向 te.exe；

• 运行测试（架构需与测试构建目标一致，x86/x64）：

  te.exe Console.Unit.Tests.dll
  

  支持通配符与多个测试二进制；用 /name: 按类/方法名限定范围：

  te.exe Console.Unit.Tests.dll /name:*BufferTests*
  

  te.exe /! 可输出内置帮助；

• PowerShell 方式：Import-Module .\tools\OpenConsole.psm1; Invoke-OpenConsoleTests，Invoke-OpenConsoleTests -? 可列出全部选项；

• 调试测试：加 /waitForDebugger 参数（如 runut *Tests.dll /name:TextBufferTests::TestInsertCharacter /waitForDebugger），TAEF 会输出 “Waiting for debugger - PID ... @ IP ...”，随后用 Visual Studio 的 “Attach To Process” 或 WinDbg 附加到该进程，断点即可命中。

仓库中测试工程按 doc/ORGANIZATION.md 的约定组织：单元测试放在各项目的 ut_ 子目录（如 src/host/ut_host），功能测试在 ft_ 子目录（如 src/host/ft_host、src/winconpty/ft_pty）；CONTRIBUTING 精神要求新代码在 ut_ 中贡献对应单元测试。测试列表定义在 src/testlist 下的 *.testlist 文件中。

七、代码评审、合并与代码风格

评审与合并流程

• 当希望团队查看工作时（即使尚未完全完成），将 PR 从草稿标记为 “Ready For Review”，团队会给出评论、建议或要求修改；
• 评审可能经历多个循环，但最终结果是“扎实、可测试、合规、可安全合并”的代码；
• 代码经所需数量的团队成员评审批准后合入主分支，PR 随之自动关闭；
• PR 提交时填写 .github/PULL_REQUEST_TEMPLATE.md 模板，要求包含：Summary、关联的 References/Relevant Issues、详细描述与补充说明、Validation Steps Performed，以及 PR 检查清单（Closes #xxx、Tests added/passed、Documentation updated、Schema updated if necessary）。

代码风格与组织约束

CONTRIBUTING.md 未展开的“质量条”由配套文档定义，贡献代码前应遵循：

• doc/STYLE.md：往既有类/函数中插入代码时严格贴合现有风格；全新代码或整块重构尽量走 Modern C++，参考 C++ Core Guidelines；操作 Win32/NT API 时优先使用 WIL（Windows Implementation Library）的智能指针与结果处理器；不鼓励用 NTSTATUS 作返回码，优先 HRESULT 或异常，返回状态码的函数应标 noexcept 且加 nodiscard；在 TerminalApp 中编写 C++/WinRT 代码时正确使用 strong/weak 引用并理解其并发模型；
• doc/ORGANIZATION.md：遵循“随现有代码模式”原则；新想法打包成接口清晰的库或类；每个项目配 ut_ 单元测试目录、功能测试放 ft_ 目录、构建脚本按输出类型放在 /dll、/exe 子目录、接口放 inc 目录、相关库放在一起（如 src/terminal/parser 与 src/terminal/adapter）。该文档还给出了 src/cascadia（TerminalConnection/TerminalCore/TerminalControl/TerminalApp/WindowsTerminal/CascadiaPackage 等）、src/host（控制台主机主体）、src/renderer、src/terminal（VT 解析与适配）等核心目录的职责说明，是定位改动影响面的地图；
• 格式化：仓库提供 .clang-format 配置，可用 Invoke-CodeFormat / runformat 统一格式，.editorconfig 约束通用缩进等编辑器行为。

八、参考文件速查

主题	仓库内位置
贡献总纲	CONTRIBUTING.md
机器人/标签规则	doc/bot.md
安全漏洞上报	SECURITY.md
构建与环境	doc/building.md、README.md、tools/OpenConsole.psm1
TAEF 测试	doc/TAEF.md、doc/UniversalTest.md
Issue 模板	Bug_Report.yml、Feature_Request.yml、config.yml
PR 模板	PULL_REQUEST_TEMPLATE.md
Spec 模板与实例	spec-template.md、doc/specs
代码风格/组织	doc/STYLE.md、doc/ORGANIZATION.md、doc/WIL.md

走完上述流程——公开透明的沟通、标签驱动的 bot 维护、带足环境信息与复现步骤的 issue、按模板落地的 spec、tools/OpenConsole.psm1 与 TAEF 支撑的本地构建测试、与官方 Windows 源码同等力度的评审——就构成了向 OpenConsole 仓库提交一次合格贡献的完整闭环。