positron-pr-helper

Positron PR ヘルパー

このスキルは、ソースオブトゥルースから最新の E2E テストタグを直接取得し、posit-dev/positron リポジトリ向けの包括的な PR 本文を作成するのに役立ちます。

このスキルを使用するタイミング

以下の場合にこのスキルを使用してください：

• 新しい PR を作成する際に、適切に構成された本文が必要な場合
• 既存の PR 本文を正しい形式に更新する場合
• 検証手順で使用する現在の E2E テストタグ一覧が必要な場合
• PR 本文が Positron の規約に沿っていることを確認したい場合
• PR を開く前にテストカバレッジの確認（PETE）を行いたい場合

前提条件

• GitHub CLI（gh）がインストールされ、認証済みであること
• Positron リポジトリ内で作業していること
• リポジトリの test-tags.ts ファイルにアクセスできること

ワークフロー

包括的な PR 本文の作成を案内します：

Step 1: コンテキストを収集する

まず、以下を確認します：

1. Issue 番号（この PR が特定の Issue に対応する場合）
2. PR の種類（バグ修正、機能追加、UI の変更、保守作業など）
3. 概要（この PR の内容）
4. スクリーンショットが必要か？（UI の変更の場合）
5. 関連する PR（例：ark リポジトリ内の PR）

Issue 番号が指定された場合は、gh issue view を使って詳細を取得し、コンテキストをより深く把握します。

Step 2: 現在のテストタグを取得する

抽出スクリプトを使って、test/e2e/infra/test-runner/test-tags.ts から現在の E2E テストタグを動的に取得します。これにより、以下を含む最新かつ完全なタグ一覧を常に利用できます：

• 機能タグ（機能固有）
• プラットフォームタグ（OS／環境の制御）
• パフォーマンスタグ
• 特殊タグ（critical、soft-fail）

Step 3: テストカバレッジを評価する（PETE）

検証手順の草案を作成する前に、ローカルの PETE プレビュー（pete スキル。.claude/skills/pr-test-checker/SKILL.md と評価基準を共有しており、CI の PR Test Checker が使うものと同じです）を作業ツリーに対して実行します。これにより、テストタグを確認するのと同じ方法で変更のテストカバレッジを確認します：

• 実質的なソースコードの変更にユニットテスト／E2E テストのカバレッジがない場合にフラグを立てます（判定：Insufficient）
• 変更をすでにカバーしている既存の E2E テストのうち、PR 本文に @: タグがないものを提示します。これらは Step 2 のタグ一覧に含めます
• 検証手順で明記する価値のある、Windows／Web デプロイの不足点を記録します

PETE が Insufficient と判定した場合は、その旨を伝え、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 で確認済みです）。

そのため、タグ文字が続く文字列 @: は、Validation Steps セクション内で、CI に実行させたいタグに限って記述してください。PR 本文のそれ以外の場所（Summary、QA Notes、影響範囲や該当領域を説明する箇条書きなど）では、@: を付けずに領域名で言及してください。たとえば、「sessions、apps、viewer の各スイート」や「sessions ヘルパーに広く影響します」とし、括弧書きで「@:sessions @:apps @:viewer」とは書かないでください。タグの自動検出を修正する PR など、タグ付けシステム自体について説明する必要がある場合も同じルールが適用されます。タグ名で説明し、@: 形式では書かないでください。

PR 本文を確定する前に、Validation Steps セクション外に @: がないか草案を確認し、見つかった場合は表現を修正してください。

ステップ 4：PR 本文の作成

PR の種類とコンテキストに基づいて、次の構成で PR 本文を作成します。

1. 冒頭の一文

   • 該当する場合は「Fixes #[issue]」を記載します。GitHub のクローズキーワード（Fixes、Closes、Resolves）を使うと、PR のマージ時に issue が自動的にクローズされます
   • それ以外の場合は、PR の内容を簡潔に説明します

2. 説明／概要

   • 変更内容を簡潔に説明します
   • 必要に応じて技術的な背景を記載します
   • 関連する PR を参照します

3. スクリーンショット（UI の変更がある場合のみ）

   • プレースホルダーテキスト、または提供された実際の URL

4. リリースノート

   • 新機能（該当する場合）
   • バグ修正（該当する場合）
   • ユーザー向けの説明

5. 検証手順

   • 影響を受ける領域に応じた関連する E2E テストタグ
   • テスト手順
   • 役立つ場合はコード例
   • ステップ 3 での PETE の判定が「不十分」だった場合は、その旨の注記

ステップ 5：出力方法の選択

PR 本文の準備ができたら、次の方法から選択できます。

1. クリップボードにコピー（Mac のみ） - pbcopy を使用します
2. 既存の PR を更新 - gh pr edit を使用します
3. ファイルに保存 - 任意のファイルに書き込みます
4. 表示のみ - 手動でコピーできるように表示します

ヘルパースクリプト

fetch-test-tags.sh

このスクリプトは、TypeScript の enum からすべてのテストタグを抽出し、分類します。

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

このスクリプトは次の処理を行います。

• TypeScript のコンパイルなしで test-tags.ts を解析します
• タグを自動的に分類します（機能、プラットフォーム、パフォーマンス、特殊）
• 用途に応じて複数の形式で出力します
• 高速に実行されます（1 秒未満）

PR 本文のテンプレート

PR の種類に応じて、異なるテンプレートを使用します。

バグ修正テンプレート

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：バグ修正 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. 接続ペインにテーブルが表示されることを確認します

## 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)