Positron 仓库 PR Body 编写规范与模板参考：从模板结构到 e2e 测试标签触发机制

• 开发工具
• 代码编辑器
• 数据科学

导读

本文基于 Positron 仓库的 PR Body 模板参考 文档，系统梳理 Positron 项目中 PR 描述（PR Body）的标准结构、六类 PR 类型模板、Release Notes 写法规范与 Validation Steps 最佳实践。同时结合仓库内的 PR Helper Skill、e2e 测试标签定义 与 CI 标签解析脚本，深入讲解@:测试标签的真实触发机制与安全书写规则。读完本文，你将能写出符合 Positron 社区规范、能正确驱动 CI 测试的规范化 PR 描述。

一、PR Body 模板总览：组件与结构

PR 描述是 Positron 仓库中每一次代码变更的“门面”，它既要让评审者快速理解改动意图，也要让 CI 系统从中解析出需要执行的 e2e 测试套件。模板参考文档将 PR Body 拆解为两个核心组件：

1.1 开头行（Opening Line）模式

有关联 Issue 时，使用 GitHub 的关闭关键词（Fixes、Closes、Resolves），使 PR 合并时 Issue 自动关闭：

Fixes #[issue_number]

无关联 Issue 时，直接写一句简要陈述，说明 PR 做了什么：

[Brief statement of what the PR does].

多个 Issue 时，每个 Issue 都必须自带关闭关键词，GitHub 才能逐个关联并关闭：

Fixes #[issue1], fixes #[issue2], and fixes #[issue3]

1.2 描述（Description）模式

简单描述（2-3 句）：

This PR [what it does]. The [root cause/reason]. [Any important implementation detail].

复杂描述（带标题与关联 PR）：

### Summary [Paragraph explaining the changes] [Technical context paragraph if needed] Related PRs: - posit-dev/ark#[number] - [description] - posit-dev/positron-python#[number] - [description]

Positron 是数据科学 IDE，其内核（ark）、Python 语言支持（positron-python）等位于独立仓库，因此跨仓库 PR 联动（Paired PRs）在描述中很常见，SKILL.md 的 Step 1 也专门要求收集“Related PRs（例如在 ark 仓库中）”信息。

二、六类 PR 类型模板：完整参考与逐项解析

模板参考文档按 PR 类型给出了六个可直接套用的模板。以下是完整继承并补充注释的版本。

2.1 Bug Fix（缺陷修复）

Fixes #[issue] This PR fixes [the problem]. The issue was caused by [root cause]. [Implementation approach if non-obvious]. ### Release Notes #### New Features - N/A #### Bug Fixes - [User-facing description of fix] (#[issue]) ### Validation Steps [relevant tags] [Simple reproduction steps and verification]

要点：Bug Fix 描述应点明“问题是什么、根因是什么、实现方式是否常规”。Release Notes 中的 Bug Fixes 条目必须写用户视角的描述，并带上 Issue 编号。SKILL.md 中的示例（Fix Data Explorer 滚动条在 Safari 上弹回 0）正是这一模板的标准演绎。

2.2 New Feature（新功能）

Fixes #[issue] ### Summary This PR adds [feature description]. Users can now [what they can do]. [Technical implementation paragraph] [Related PRs if any] ### Release Notes #### New Features - [User-facing feature description] (#[issue]) #### Bug Fixes - N/A ### Validation Steps [relevant tags] [Numbered steps for testing]: 1. [Setup step] 2. [Action step] 3. [Verification step] ```[language] [Code example if helpful]

要点：新功能 PR 的 Validation Steps 建议使用**编号步骤**（设置 → 操作 → 验证），必要时附可运行的代码示例。SKILL.md 的 Example 2（原生 DuckDB 连接支持）展示了带 Python 代码示例的完整写法。 ### 2.3 UI/UX Change（界面变更） ```markdown Fixes #[issue] This PR [describes the UI change]. The change improves [what it improves]. [Screenshot: Description of what the screenshot shows] ### Release Notes #### New Features - [User-visible UI change] (#[issue]) #### Bug Fixes - N/A ### Validation Steps [relevant tags including UI-specific ones] 1. [Navigate to the UI element] 2. [Perform the action] 3. [Verify the new behavior]

要点：UI 变更是唯一明确要求配截图的类型，截图后应紧跟一句说明截图内容的文字。验证步骤按“定位 UI 元素 → 执行操作 → 验证新行为”三段式组织，标签需包含 UI 相关套件（如@:editor-action-bar、@:top-action-bar、@:layouts等）。

2.4 Performance Improvement（性能优化）

Fixes #[issue] ### Summary This PR optimizes [what was optimized]. Performance improves by [metrics/percentage] for [use case]. **Before:** [performance characteristic] **After:** [improved characteristic] ### Release Notes #### New Features - N/A #### Bug Fixes - N/A #### Performance - [User-facing performance improvement] (#[issue]) ### Validation Steps @:performance [other relevant tags] [Steps to verify performance improvement]

要点：性能优化模板独特之处在于：

• Release Notes 有独立的#### Performance小节；
• 要求在Before / After中给出可度量的性能特征（指标或百分比）；
• Validation Steps 首行使用@:performance标签——它在 FeatureTags 枚举 中是独立的功能标签，会触发性能测试套件。

2.5 Maintenance/Refactoring（维护与重构）

[Brief description of maintenance work]. ### Summary This PR [refactoring description]. No user-facing changes. [Technical justification] ### Release Notes #### New Features - N/A #### Bug Fixes - N/A ### Validation Steps [relevant tags] Verify existing functionality still works: 1. [Test area 1] 2. [Test area 2]

要点：维护型 PR 明确声明“No user-facing changes”，Release Notes 全部为 N/A，验证重点转为回归验证——确认既有功能不受影响。

2.6 E2E Test Addition（e2e 测试新增）

Adds e2e tests for [feature/area]. This PR adds comprehensive test coverage for [what's being tested]. The tests verify [key behaviors]. ### Validation Steps [tags for the areas being tested] Run the new tests: ```bash npx playwright test [test-file-name] --project e2e-electron

要点：测试类 PR 关注“覆盖了什么、验证了什么行为”，并提供可复现的测试运行命令。仓库 e2e 测试基于 Playwright，项目根目录的 [playwright.config.ts](https://link.gitcode.com/i/8ff4dcff186662d0f37ee6253973fd46) 定义了测试项目配置。 ## 三、Release Notes 撰写规范：好例子与坏例子 模板参考文档给出了明确的判别标准，核心原则是**面向用户、避免实现细节**。 **Features 好例子：** - ✅ "Added support for Python 3.12 virtual environments" - ✅ "Jupyter notebooks now support collapsible cell outputs" - ✅ "New keyboard shortcut <kbd>Cmd+Shift+P</kbd> opens command palette" **Bug Fixes 好例子：** - ✅ "Fixed Data Explorer scrolling on Safari" - ✅ "Resolved console output truncation for long lines" - ✅ "Connections pane now correctly displays schema names with spaces" **Too Technical（过于技术化，❌）：** - ❌ "Refactored AbstractKernelManager to use dependency injection" - ❌ "Fixed race condition in async state machine" **Too Vague（过于含糊，❌）：** - ❌ "Improved performance" - ❌ "Fixed various bugs" - ❌ "Updated UI" 判别逻辑很清晰：`AbstractKernelManager`、`dependency injection` 这类实现术语属于源码内部语言；而 "Improved performance" 这类宽泛表述又无法让用户感知任何具体收益。正确的写法应落在“用户能观察到什么变化”这一层。键盘快捷键统一用 `<kbd>` 标签包裹，Issue 引用统一用 `#[number]` 格式。 ## 四、Validation Steps 最佳实践：标签选择与测试指引 ### 4.1 标签选择原则 模板参考文档给出的选择规则为： - **功能标签**用于功能变更； - **平台标签**仅在需要平台相关测试时添加； - **`@:critical`** 仅用于关键路径功能； - **不要过度打标签**，聚焦主要受影响区域。 这套规则与 [test-tags.ts](https://link.gitcode.com/i/5a02c373cbf8053049fc1cd391930183#L6-L39) 的注释完全对应：FeatureTags（`@:console`、`@:connections`、`@:data-explorer`、`@:duck-db` 等）运行在默认的 Linux/Electron 通道；PlatformTags（`@:win`、`@:web`、`@:rocky-electron`、`@:workbench` 系列等）各自触发独立的 CI 任务；`@:critical` 具有特殊行为。从源码结构看，[fetch-test-tags.sh](https://link.gitcode.com/i/1c165362e1e67f25ed618e9aa64d33ac) 正是按这三类（外加 performance）对标签做分类提取的。 ### 4.2 测试指引示例 **简单修复：**

@:console

Run any Python code in the console and verify output appears correctly.

**复杂功能（DuckDB 连接）：**

@:connections @:duck-db

1. Install DuckDB:pip install duckdb
2. Create connection via File > New Connection > DuckDB
3. Select "In-memory database" option
4. Run the test script:

import duckdb conn = duckdb.connect() conn.execute("CREATE TABLE test (id INT, name VARCHAR)") conn.execute("INSERT INTO test VALUES (1, 'test')")

5. Verify table appears in Connections pane
6. Double-click table to preview data

复杂功能的测试指引应包含安装依赖、创建连接的完整路径、可执行代码脚本以及逐条验证步骤，确保任何评审者都能复现。 ## 五、常见模式：Paired PR、Breaking Changes 与文档更新 ### 5.1 Paired PRs（跨仓库联动 PR） 当 PR 依赖其他仓库的变更时，明确标注合并顺序：

Related PRs (merge in order):

1. posit-dev/ark#123 - Kernel support (merge first)
2. This PR - UI integration
3. posit-dev/positron-python#456 - Language server support (optional)

这一模式与 Positron 的多仓库架构（ark 内核、positron-python 语言支持）强相关，[SKILL.md](https://link.gitcode.com/i/ca7252c8993ae48376de761cd2f447e1) 的工作流也把 Related PRs 作为标准上下文信息收集。 ### 5.2 Breaking Changes（破坏性变更） 必须包含迁移说明，并给出 Before/After 对比：

⚠️ Breaking Changes

This PR changes [what changes]. Users will need to [migration steps].

Before:old_api_call()After:new_api_call(param)

### 5.3 Documentation Updates（文档更新） 当 PR 配套文档变更时，引用对应文档仓库的 PR：

Documentation: posit-dev/positron-docs#789

## 六、`@:` 标签的 CI 触发机制：为什么必须严守书写位置 这是本文要特别强调的**安全红线**。SKILL.md 的 "Tag Safety" 一节明确指出：CI 的 [pr-tags-parse.sh](https://link.gitcode.com/i/5787e7d23a786e9f7021f191a2b9d55c) 用 `grep -o "@:[a-zA-Z0-9_-]*"` 对 **PR Body 全文**做原始子串匹配，它对 Markdown 结构毫无感知——一个字面上的 `@:tag` 子串，无论出现在哪个章节、是否在反引号代码块内、是真实指令还是行文中顺带提及，都会触发对应套件的 CI 任务。反引号引用**不能**提供保护（该行为已在 PR #14734 上确认）。 因此规则是： 1. **`@:` 前缀的字面字符串只能出现在 Validation Steps 章节**，且只能用于你确实希望 CI 运行的标签； 2. 在 Summary、QA Notes、影响范围说明等其余位置，一律用**不带 `@:` 前缀**的名称指代测试区域，例如写 "the sessions, apps, and viewer suites"，而不要写成 "`@:sessions @:apps @:viewer`" 作为括注； 3. 即使 PR 本身是修复标签自动检测系统，讨论标签机制时同样只能描述标签名称，不能拼写出 `@:` 形式； 4. 提交前扫描草稿，清除 Validation Steps 之外的所有 `@:`。 从 [pr-tags-parse.sh](https://link.gitcode.com/i/5787e7d23a786e9f7021f191a2b9d55c#L152-L198) 的实现可以印证这一机制的完整链路：脚本先探测 `@:all`（运行全部测试）；否则提取全部 `@:` 标签，过滤 `@:no-auto-tags` 逃生舱口，然后**对照 [test-tags.ts](https://link.gitcode.com/i/5a02c373cbf8053049fc1cd391930183) 枚举校验标签合法性**（拼写错误的标签会被剔除并在 PR 评论中警告），最后无条件补上 `@:critical` 保底。此外脚本还会根据 PR 改动文件自动派生标签：改动 ark 子模块自动注入 `@:ark`、`@:win`、`@:web`；通过 [test-tag-paths-map.json](https://link.gitcode.com/i/0b5ab650869f2c082890974136bfcfbb) 路径映射为源码改动派生功能标签（除非作者写了 `@:no-auto-tags` 显式退出）。 ### 自动标签派生对写 PR 的启示 正因为 CI 会自动派生标签，PR 作者在 Validation Steps 中**手写**的标签应当聚焦于自动派生覆盖不到的部分：平台标签（`@:win`、`@:web`、Rocky/openSUSE/SLES/Debian 系列）必须作者手动添加才能开启对应平台通道；而功能标签即使不写，改动对应源码目录时也会被路径映射自动补上。这与模板参考文档“不要过度打标签，聚焦主要受影响区域”的原则互为补充。 ## 七、风格指南：语言与格式 ### 7.1 语言规范 - **现在时**描述行为："Fixes"、"Adds"、"Enables"； - **主动语态**："This PR fixes..."，而不是 "The bug is fixed by..."； - **简洁**：删掉一切多余词汇； - **面向用户**：聚焦影响而非实现。 ### 7.2 格式规范 - 代码、命令、文件名使用反引号 `` ` ``； - 强调用 **粗体**，克制使用； - 键盘快捷键用 `<kbd>` 标签； - Issue 链接统一用 `#[number]` 格式； - 代码块带语言提示（` ```python `、` ```bash `）。 ### 7.3 应当避免的内容 - 🚫 华丽辞藻或不必要的上下文； - 🚫 Release Notes 中的实现细节； - 🚫 道歉或自我贬低； - 🚫 Commit 消息列表（PR Body 应做总结而非罗列）； - 🚫 TODO 项（应放到 Issue 中）； - 🚫 疑问句（在创建 PR 前解决所有问题）。 ## 八、配套工作流：Positron PR Helper Skill 仓库中的 [SKILL.md](https://link.gitcode.com/i/ca7252c8993ae48376de761cd2f447e1) 将上述模板落地为一个五步工作流： 1. **收集上下文**：Issue 编号、PR 类型、Summary、是否需要截图、关联 PR；有 Issue 时用 `gh issue view` 拉取详情； 2. **动态拉取测试标签**：通过 [fetch-test-tags.sh](https://link.gitcode.com/i/1c165362e1e67f25ed618e9aa64d33ac) 从 `test/e2e/infra/test-runner/test-tags.ts` 提取当前完整标签清单（脚本无需 TypeScript 编译，通过 grep/sed 解析枚举，支持 `markdown`、`json`、`list` 三种输出格式，运行时间 <1 秒）； 3. **PETE 测试覆盖评估**：本地预览检查测试覆盖，若判定 Insufficient 则必须补充具体测试建议，不得用空泛的 Validation Steps 掩盖；PR 打开后可在 CI 中通过 `/pete` 评论获取权威结论； 4. **生成 PR Body**：按类型模板组装（开头行 → 描述/Summary → 截图 → Release Notes → Validation Steps）； 5. **输出**：支持复制到剪贴板（`pbcopy`，仅 Mac）、`gh pr edit` 更新既有 PR、写入文件或直接展示。 ## 结语 Positron 的 PR Body 规范本质上是一套“**人机双读**”约定：人类评审者从 Summary 与 Release Notes 快速理解改动，CI 系统则从 Validation Steps 的 `@:` 标签精确调度 e2e 测试。遵循本文的模板结构、Release Notes 用户视角原则、标签选择规则，并严守 `@:` 标签只能出现在 Validation Steps 的红线，就能让每一次代码合入既清晰可读，又精准触发应有的测试覆盖。相关模板全文可查阅 [pr-templates.md](https://link.gitcode.com/i/c4abcdd76e8967cf629d265ece2fc924)，标签定义与 CI 解析逻辑可分别深入 [test-tags.ts](https://link.gitcode.com/i/5a02c373cbf8053049fc1cd391930183) 与 [pr-tags-parse.sh](https://link.gitcode.com/i/5787e7d23a786e9f7021f191a2b9d55c)。

• 开发工具
• 代码编辑器
• 数据科学