simple-issue-description

シンプルなIssueの説明

メンテナーが1分以内に理解できるIssueを書きます。ユーザーがどのような状況に遭遇するか、代わりにどう動作すべきかに焦点を当てます。

ワークフロー

1. 提供されたメモ、会話、Issue、PRの説明、または差分を読みます。PRの場合は、仕様書、設計ドキュメント、READMEの変更も確認します。説明よりも意図が明確に記されていることがよくあります。
2. 具体的な問題を特定します。情報源から影響を受ける人やものが明らかな場合は、それを明記します。
3. 実装方法を指定せずに、望ましい動作を説明します。
4. 問題を理解したり再現したりするのに役立つ背景情報だけを残します。
5. 情報源がPRや差分の場合は、変更したファイルやコードではなく、その変更が解決しようとしている問題を説明します。
6. 問題と望ましい動作を判断できない場合を除き、すぐにIssueの草案を作成します。判断できない場合は、簡潔な確認質問を1つします。

問題ごとにIssueを1つ作成します。情報源に無関係な問題がまとめられている場合は、最も重要な問題についてIssueを作成し、残りはそれぞれ1行で列挙して、投稿者に個別のIssueとプルリクエストに分けるよう伝えます。

情報源が不具合の修正ではなく機能の追加である場合、機能がないことをバグとして扱わないでください。現時点でユーザーにできないことと、その機能を利用するユーザー、利用する場所、表示される内容を含む、機能の利用体験をすべて説明します。

情報源に裏付けられていないユーザーへの影響、再現手順、確実性を捏造しないでください。情報源が示しているのがクリーンアップ、リファクタリング、または潜在的なコードの問題だけである場合は、問題を無理に作り出さず、具体的な問題が明らかでないと伝えます。このルールは手順6より優先されます。情報源から読み取れることと、Issueに値する根拠となる情報を、2～3文で回答します。

情報源がまだ公開されていないセキュリティ上の弱点を修正するものである場合、その問題を説明する公開Issueは作成しないでください。代わりに、メンテナーへ非公開で報告するよう提案します。

文章作成ルール

• 平易な言葉と短い文を使います。
• 再現手順や大規模な機能の説明に明らかに必要な場合を除き、Issueは200語未満にします。
• コード、アーキテクチャ、提案する修正ではなく、動作から書き始めます。症状を理解するうえで原因の説明が欠かせない場合は、平易な言葉で1文だけ原因を説明してもかまいません。
• 再現や問題の理解に必要な技術的な詳細だけを残します。症状を理解するうえで必要な制限やデフォルト値（バッチサイズ、クォータ、上限など）は含めます。
• エラーメッセージ、スクリーンショット、リンク、ドキュメントへの参照など、役立つ根拠は残します。
• AIがIssueを作成またはレビューしたことには触れません。
• 水増しの表現、称賛、ロードマップに関する文言、あらゆるエッジケースの網羅は避けます。
• 投稿者が示す確実性の度合いを保ちます。推測を確認済みのバグとして示さず、情報源がリスクを述べているだけの場合は「可能性があります」などの表現を使います。

出力形式

最初の行はIssueのタイトルです。GitHubに投稿する場合は、本文で繰り返さずタイトル欄に記入します。機能の追加の場合は、偽のバグのようなタイトル（「監査で構造化データに言及しない」）ではなく、実現する結果をタイトルにします（「構造化データのないページにフラグを付ける」）。

追加できる有用な情報がない場合は、追加のコンテキストセクションを省略します。制約や対象範囲に関する注記はこのセクションに記載します。メンテナーが当然懸念する可能性のある、対象外のものも含めます。

# <Short title describing the problem or desired outcome>

## TL;DR

<In one or two sentences, explain what happens now and what should happen instead.>

## What is happening?

<Describe the current behavior in plain language. Include a concrete example when available.>

## What should happen?

<Describe the desired behavior without proposing how to build it.>

## Extra context

<Optional reproduction steps, error text, screenshots, links, or constraints.>

例

# The chat jumps away from messages I am reading

## TL;DR

When I scroll up to read an older message, a new response moves me back to the bottom of the chat. The chat should stay where I left it until I choose to return to the latest message.

## What is happening?

New responses automatically scroll the chat to the bottom, even when I am reading earlier messages.

## What should happen?

Keep my current scroll position and show that a new message is available.