positron-pr-helper

Positron PR 助手

此技能可帮助你为 posit-dev/positron 仓库编写全面的 PR 正文，并直接从事实来源获取最新的端到端（e2e）测试标签。

何时使用此技能

在以下情况下使用此技能：

• 创建新的 PR，需要结构清晰的正文
• 更新现有 PR 正文，使其采用正确格式
• 需要获取当前的 e2e 测试标签列表，以用于验证步骤
• 希望确保 PR 正文符合 Positron 约定
• 希望在开启 PR 前检查测试覆盖率（PETE）

先决条件

• 已安装并完成身份验证的 GitHub CLI（gh）
• 正在 Positron 仓库中工作
• 可访问仓库的 test-tags.ts 文件

工作流

我会引导你编写全面的 PR 正文：

步骤 1：收集背景信息

首先，我会询问你：

1. Issue 编号（如果此 PR 针对某个特定 issue）
2. PR 类型（错误修复、功能、UI 更改、维护等）
3. 摘要，说明此 PR 的作用
4. 是否需要截图？（适用于 UI 更改）
5. 相关 PR（例如，ark 仓库中的 PR）

如果你提供了 issue 编号，我会使用 gh issue view 获取详细信息，以便更好地了解背景。

步骤 2：获取当前测试标签

我会使用提取脚本，从 test/e2e/infra/test-runner/test-tags.ts 动态获取当前的 e2e 测试标签。这能确保我们始终拿到完整且最新的标签列表，包括：

• 功能标签（针对特定功能）
• 平台标签（用于控制操作系统／环境）
• 性能标签
• 特殊标签（critical、soft-fail）

步骤 3：评估测试覆盖率（PETE）

在起草验证步骤之前，我会针对你的工作树运行本地 PETE 预览（pete 技能与 .claude/skills/pr-test-checker/SKILL.md 共用评分标准，也就是 CI 的 PR Test Checker 使用的同一套标准）。它会像我检查测试标签一样检查测试覆盖率：

• 标记没有单元／e2e 覆盖的实质性源代码更改（判定：覆盖不足）
• 找出已有 e2e 测试覆盖了相关更改、但 PR 正文中缺少对应 @: 标签的情况——这些标签会并入步骤 2 获取的标签列表
• 指出值得在验证步骤中说明的 Windows／Web 部署缺口

如果 PETE 报告覆盖不足，我会告知你，并在最终确定 PR 正文前建议具体的补充方案（文件路径、运行器、测试内容）——我不会用泛泛的“验证步骤”部分来掩盖覆盖率缺口。这只是本地预览，不会取代官方检查；目前官方检查会在 CI 中按需运行——PR 开启后，在 PR 中评论 /pete（或 /recheck-tests、/rePETE、/re-pete）即可获取权威判定。

标签安全：只在确实需要触发时才写入 @:tag

scripts/pr-tags-parse.sh（CI）会通过对整个 PR 正文文本执行原始 grep -o "@:[a-zA-Z0-9_-]*" 来提取标签。它无法识别 Markdown 结构——无论 @:tag 字符串出现在正文的哪个部分、是否放在反引号中，也无论你是想把它作为真正的指令，还是只是在文字中提及标签名称，只要出现这个字符串，就会触发对应测试套件的 CI 作业。使用反引号并不能避免触发（已在 PR #14734 中确认）。

因此：字面字符串 @: 后接标签字符的内容，只能出现在“验证步骤”部分，而且只能用于你确实希望 CI 运行的标签。在 PR 正文的其他位置（摘要、QA 说明、解释影响范围或受影响区域的项目符号等），请直接使用区域名称，不要加 @: 前缀——例如“sessions、apps 和 viewer 测试套件”，或“广泛影响 sessions 辅助工具”，绝不要用“@:sessions @:apps @:viewer”作为括号中的补充说明。如果你需要讨论标签系统本身（例如，某个 PR 修复了标签自动检测），也要遵循同一规则：只描述标签名称，不要写出 @: 形式。

在最终确定任何 PR 正文之前，请检查草稿，找出“验证步骤”部分以外的 @:，并改写相关内容。

第 4 步：生成 PR 正文

根据 PR 类型和上下文，我会创建结构化的 PR 正文，包括：

1. 开场行

   • 如果适用，使用 GitHub 关闭关键词（Fixes、Closes、Resolves）填写“Fixes #[issue]”，以便 PR 合并时自动关闭问题
   • 否则简要说明 PR 的作用

2. 描述/摘要

   • 简洁说明变更
   • 必要时提供技术背景
   • 引用相关 PR

3. 截图（仅适用于 UI 变更）

   • 占位文本或提供的实际 URL

4. 发布说明

   • 新功能（如适用）
   • Bug 修复（如适用）
   • 面向用户的说明

5. 验证步骤

   • 根据受影响区域提供相关的端到端测试标签
   • 测试说明
   • 有帮助的代码示例
   • 如果第 3 步中 PETE 的判定为 Insufficient，则添加相关说明

第 5 步：输出选项

PR 正文准备就绪后，你可以选择：

1. 复制到剪贴板（仅限 Mac）——我会使用 pbcopy
2. 更新现有 PR——我会使用 gh pr edit
3. 保存到文件——我会写入你指定的文件
4. 仅显示——我会显示内容，供你手动复制

辅助脚本

fetch-test-tags.sh

此脚本会从 TypeScript 枚举中提取并分类所有测试标签：

# Usage:
./scripts/fetch-test-tags.sh [format]
# format: markdown (default), json, or list

此脚本：

• 解析 test-tags.ts，无需编译 TypeScript
• 自动对标签进行分类（功能、平台、性能、特殊）
• 以多种格式输出，适用于不同场景
• 运行速度快（<1 秒）

PR 正文模板

我会根据 PR 类型使用不同的模板：

Bug 修复模板

Fixes #[issue]

[2-3 sentences explaining the fix]

### Release Notes

#### New Features
- N/A

#### Bug Fixes
- [User-facing description] (#[issue])

### Validation Steps

[relevant tags]

[Simple test instructions]

新功能模板

Fixes #[issue]

### Summary
[1-2 paragraphs explaining the feature]
[Technical implementation notes if relevant]
[Related PRs if applicable]

### Release Notes

#### New Features
- [User-facing description] (#[issue])

#### Bug Fixes
- N/A

### Validation Steps

[relevant tags]

[Detailed test steps with code examples]

示例

示例 1：Bug 修复 PR

Fixes #8930

This PR fixes the Data Explorer scrollbars snapping back to 0 on Safari. The issue was caused by incorrect event handling in the virtual scrolling implementation.

### Release Notes

#### New Features
- N/A

#### Bug Fixes
- Fix Data Explorer scrollbars snapping back to 0 on Safari (#8930)

### Validation Steps

@:data-explorer

Open a large data frame in Data Explorer on Safari and verify scrollbars can be dragged without snapping back.

示例 2：新功能 PR

Fixes #8484

### Summary
Adds support for native DuckDB connections in the Connections Pane. Users can now inspect DuckDB databases directly without needing external tools. This implementation uses the native DuckDB Python API for better performance.

Related PR: posit-dev/ark#456 (adds DuckDB kernel support)

### Release Notes

#### New Features
- Added support for inspecting native DuckDB connections in the Connections Pane (#8484)

#### Bug Fixes
- N/A

### Validation Steps

@:connections @:duck-db

1. Install DuckDB: `pip install duckdb`
2. Create a new DuckDB connection using the modal
3. Run the following to create test data:

```python
conn.execute("""
    CREATE TABLE employees (
        id INTEGER,
        name VARCHAR,
        salary INTEGER
    )
""")
conn.execute("INSERT INTO employees VALUES (1, 'Alice', 75000)")

4. 验证 Connections 窗格中是否显示表格

## Tips

- Be concise but complete - no flowery language
- Use present tense ("fixes", "adds", "enables")
- Include issue references in parentheses in release notes
- Always include at least one e2e test tag in validation steps
- Never write a literal `@:tag` outside the Validation Steps section -- CI's tag parser matches the substring anywhere in the body, in prose or backticks alike, and will trigger that suite unintentionally
- For complex changes, numbered test steps are better
- Keep release notes user-facing (avoid implementation details)