writing-issues-and-prs

Issue と PR の書き方

どのプラットフォームでも、文章は重要な役割を果たします。ユーザーや周囲の文脈でプラットフォーム固有の用語が求められない限り、プラットフォームに依存しない表現を使ってください。

シナリオ別（バグ報告、機能リクエスト、PR/MR、作業項目、レビューコメント）の構成例については、references/outlines.md を参照してください。これらの構成例は固定テンプレートではなく、出発点です。状況に合わせて、セクションの順序を入れ替えたり、削除、追加、統合したり、新たに作成したりしてください。リポジトリやトラッカーに独自のテンプレートがある場合は、そちらを優先してください。

執筆の原則

• 簡潔にしてください。不要な語を省き、重複や曖昧な表現を削り、平易で直接的な文章を心がけてください。すべての語を大切に使いましょう。1 画面に収まらない文章は長すぎます。
• 穏やかで自然な、人間らしい調子で、正確かつ構成がよく、洞察に富んだ文章を書いてください。批判的かつ正確に、推論、情報源、前提を必ず再確認してください。
• 問題、依頼、目的を明確に述べてください。それが重要な理由を説明し、具体的な根拠を示してください。
• 英語の文章には、次のスタイルガイドに従い、言語を問わず適用できる規則はあらゆる言語の文章にも適用してください。The Elements of Style、The Sense of Style、Chicago Manual of Style。

書式ルール

• 英単語と CJK 文字の間にはスペースを入れてください。
• 順序なしリストの項目には - （ハイフンとスペース）を使ってください。* や + は使わないでください。
• 斜体には _italics_、太字には **bold** を使ってください。
• リスト項目がすべて断片的な表現の場合は、末尾にピリオドを付けないでください。完全な文が 1 つでもある場合は、すべての項目の末尾にピリオドを付けてください。
• 水平線（<hr> または ---）は使わないでください。

タイトル

• Issue と作業項目のタイトルには「Sentence case」（最初の単語のみを大文字にする）を使ってください。
• プルリクエストとマージリクエストのタイトルには、git-commit スキルに従い、Conventional Commits 形式 <type>[optional scope]: <description> を使ってください。

本文の見出し

• 見出しから書き始める必要はありません。構成を明確にするうえで役立つ場合にのみ、見出しを使ってください。冒頭に短い文や段落を置いてもかまいません。
• 見出しレベルは順番に使ってください（h2 の次は h3 など）。レベルを飛ばさないでください。
• h1 は使わず、見出しに番号を付けないでください（例：## About me ではなく ## About me）。