pr-description

プロジェクトを把握しているものの、イシュー、差分、開発時のやり取りを読んでいないレビュアー向けに、プルリクエストの説明文を作成します。仕組みを説明する前に、変更が必要な理由を明確にしてください。

ユーザーが下書きを求めた場合は、GitHub を更新せずに文章を返してください。それ以外の場合は、指定された PR の説明文を更新してください。

引数

/pr-description <PR_NUMBER> [--fixes <ISSUE_NUMBERS>]

• PR_NUMBER（必須）：説明するプルリクエスト。
• --fixes（任意）：この PR で修正するイシュー番号をカンマ区切りで指定します。例：123,456。

例：

• /pr-description 3534
• /pr-description 3534 --fixes 123,456

手順

1. 変更内容を把握します。

   • PR のタイトル、現在の説明文、ベースブランチ、ヘッドブランチを読みます。
   • PR のコミットと差分を読みます。PR の実際のベースとヘッドを使い、現在のチェックアウトが PR のブランチである、またはベースが main であると決めつけないでください。
   • 関連するイシューの詳細、コードコメント、参照できる会話の文脈を読み、問題と変更の理由を把握します。
   • --fixes とコミットメッセージ内の明示的なクローズ参照から、イシュー番号を収集します。関連するイシューだからといって、クローズ対象だと推測しないでください。

2. 既存の説明文を確認します。すでに正確で、外部の文脈がなくても理解でき、この形式に沿っている場合は、そのままにします。それ以外の場合は、追記ではなく、最終的な実装を中心に書き直します。

3. 箇条書きを選ぶ前に、説明の核を明確にします。

   • 対象のコンポーネントは何をするものですか？
   • どのような制約やニーズが、この変更のきっかけとなりましたか？
   • 変更によって、何がどのように変わりますか？ この PR を理解するのに必要な文脈だけを使います。機能やリファクタリングを正当化するために、問題をでっち上げないでください。

4. レビュアーが確認すべき、異なる論点を選びます。通常はラベル付きの箇条書き 3～6 個になります。変更が小さい場合は、もっと少なくしてください。ファイル、ヘルパー関数、実装手順ではなく、動作やシステム上の役割ごとにまとめます。

5. 差分を見ずに下書きを読み返します。目的や動作がまだ不明瞭な場合は、実装の詳細を増やす前に、必要な文脈を補います。

形式

冒頭の段落に続けて、ラベル付きの箇条書きを記載します。「Summary」「Context」「Testing」の見出しは付けません。該当する場合に限り、「Breaking Changes」と「Fixes」を含めます。

Pipecat groups streamed LLM text into sentences before sending it to TTS. This
replaces NLTK with `sentencex`, which includes its language rules and requires no
data downloads or tokenizer warm-up.

- **Streaming text.** Sentencex sometimes needs the complete word after a period
  to distinguish an abbreviation from a sentence ending. Pipecat waits for that
  word when needed, while sending sentences sooner when the ending is already clear.
- **Quoted abbreviations.** Sentencex can split after `"Dr.` before the rest of the
  quotation arrives. Pipecat rechecks these cases so it doesn't send an incomplete
  fragment to TTS.
- **TTS language.** Sentence grouping follows `Settings.language`, defaulting to
  English when unspecified. Language updates take effect before subsequent text
  is processed.

## Breaking Changes

- Sentence grouping can differ from Punkt and now follows the configured TTS language.
- Pipeline workers no longer emit tokenizer warm-up events.

冒頭の段落

コンポーネントが何をするのか、関連する制約やニーズ、変更内容を説明します。この段落だけで、PR の目的が読者に伝わるようにしてください。小さな変更なら 1 文で十分です。背景が必要な場合は、2～3 文にしてください。3 つの要素を無理に 1 つの長い文に詰め込まないでください。

背景は、変更に直接関係するものに限定します。置き換えを行う場合は、変更内で追加の対応が必要となる理由も含めて、現行の実装と提案する実装の違いを簡潔に説明するとよいでしょう。イシューへのリンクは説明を補足できますが、説明の代わりにはなりません。

ラベル付きの箇条書き

各箇条書きは、クラス、モジュール、対象領域、または動作を示す太字の名詞ラベルで始めます。Motivation、Rationale、Background、Context、Tests のような、論説的なラベルは使わないでください。

まず動作や問題を説明します。仕組みの説明は、レビュアーが変更を評価するうえで役立つ場合に限ります。通常は 1～2 文で十分です。必要な文脈や例を補う短い 3 文目を加えてもかまいません。文数の制限を満たすためだけに、まとまりのある論点を複数の箇条書きに分けないでください。

イシュー、会話、コミットメッセージ、コードから理由がわかる場合は、関連する変更の箇所にその理由を含めます。判断が正しいと主張するのではなく、満たす制約を記載します。変更前と変更後の比較は有用ですが、試した方法や採用しなかった方法の経緯は通常不要です。

用語と例

専門用語は、使う前に説明するか、一般的な言葉に置き換えてください。 「先読み（lookahead）」のようなラベルだけでは、どのテキストを調べるのか、 それがいつ届くのか、なぜ待つ必要があるのかが伝わりません。まず、そうした動作を 説明してください。

解析、順序付け、ストリーミングの変更では、抽象的な説明よりも問題が分かりやすくなる場合、 短い入力／出力の例を示してください。例は新しい API に限りません。インラインのテキストで 十分ならそれを使い、シーケンスや設定が必要な場合も、PR の説明に含めるコードブロックは 短いものを 1 つまでにしてください。

破壊的変更

ユーザー側で対応が必要な、既存の動作、シグネチャ、デフォルト値への変更がある場合は、 このセクションを含めてください。具体的な影響と、必要な移行手順を説明してください。 語数を目標内に収めるために省略してはいけません。また、追加機能が新しいというだけで 破壊的変更として扱わないでください。

修正

この PR で解決する課題には、箇条書きごとに 1 件ずつ Fixes #X を使ってください。 関連 PR や課題との関係が対象範囲の説明に役立つ場合は、冒頭の段落または該当する箇条書きに リンクできます。独立した「コンテキスト」セクションは追加しないでください。

長さと根拠

200 語未満を目指してください。ただし、その目標に合わせるために重要な背景を省略してはいけません。 まず、繰り返しの主張や、実装の二次的な詳細を削ってください。必要な長さは差分の規模ではなく、 レビュアーが理解するために必要な情報で決まります。

差分に照らして、実装と動作を正確に説明してください。問題の記述や理由は、課題、コード、 または入手可能な議論に基づかせてください。動機を作り上げたり、限定的な観察を一般化したり、 測定結果を普遍的な性能の主張に置き換えたりしないでください。

最初の文への理解を深める説明であれば、2 文目を加えても構いません。同じ情報を繰り返すだけで 読者の理解に役立たない場合に限り、その文を削除してください。

次の内容は含めないでください。

• 変更が正しいという主張や、誰も提起していない異議への回答。
• 時系列の開発経緯や、代替案を比較する段落。
• テスト件数、カバレッジ数、「すべてのテストに合格」といった記述、変更したテストの一覧、 テストコマンド。
• 変更したファイルの順を追った説明。
• 格言、宣伝文句、箇条書きの内容を締めくくる要約。

文体

この作業に詳しくないチームメイトに変更を説明するつもりで書いてください。平易な言葉と短い つながりのある文を使ってください。問題の説明に役立つ場合や、レビューに重要な場合は、 技術的な詳細も残してください。

無理に対称的な構成にしたり、3 項目を揃えたり、「X ではなく Y」の構文や、 コンマや別の文で済む箇所にダッシュの挿入句を使ったりしないでください。すべての箇条書きを 同じ形や長さにするために、分かりやすい説明を犠牲にしてはいけません。

チェックリスト

• 冒頭で、PR の目的を説明するのに十分な背景を示している。
• 読者が差分を開かなくても、関連する制限と新しい動作を説明できる。
• 箇条書きでは異なるレビュー上の論点を扱い、動作や問題から書き始めている。
• 技術用語を事前に説明し、難しいエッジケースには有用な場合に例を示している。
• 理由と変更前後の比較が、入手可能な根拠に基づいている。
• 説明が開発経緯ではなく、最終的な実装を反映している。
• 該当する場合、破壊的変更と解決する課題への参照を含めている。
• テストのセクション、テスト件数、カバレッジ数、重複する要約を含めていない。
• 必要な情報を省かず、200 語未満を目指している。