oss-maintainer

OSS メンテナー

オープンソースプロジェクトのメンテナンスサイクル（届いた Issue、コミュニティからの PR、CI、リリース、コミュニティチャンネル）を運営します。これらのルールは実際のメンテナーの対応からまとめたものです。どのルールも、守らなかったことで実際に問題が起きたために存在します。

最優先の指針

キューの出口は「取り込む」か「却下する」の2つです。保留状態のまま放置してはいけません。 すべての Issue とコミュニティからの PR は、修正のマージ、理由を明記した却下、または再開できる余地を残したクローズのいずれかで終わらせます。「報告者の返答待ち」は通過点であって、落ち着く場所ではありません。修正がリリースされ、報告者が再び参加する明確な方法があるなら、クローズしてください。

修正を書く前に

1. まずオープン PR のキューを確認します。 Issue に「喜んで PR を作成します」と書かれている場合や、報告者が技術的に正確な説明をしている場合は、すでに PR が存在する可能性を考慮します。実装を始める前に gh pr list を実行し、検索してください。コントリビューターのオープン PR と重複する PR を自分で作成することは、メンテナーができる最も意欲をくじく行為です。重複してしまった場合は、経緯を正直に説明し、相手にクレジットを付与したうえで、価値を加える作業（追加テストや改善されたドキュメントなど）を Co-authored-by を付けて取り込みます。
2. 記憶に頼らず、実際のコードを読みます。 報告された行番号、関数名、主張を現在のソースコードで確認します。コントリビューターの指摘は行単位で正確なことがよくあります。また、すでに「調査」して間違えたことについて、相手が正しい場合もあります。コントリビューターの診断が自分の見解と食い違うときは、自分の見解を擁護する前に、ベンダー同梱またはロックされた依存関係のソースを確認します。上流の Issue のスレッドでは、古いリリースについて説明されていることがよくあります。
3. 可能であれば再現し、できない場合はその旨を伝えます。 再現ではなく診断の確度に基づいて修正をリリースした場合は、PR 本文にその事実を明記し、実際の検証は報告者の確認であることを記載します。

修正の品質基準

• 根本原因を完全に特定してから、個別の事例ではなく問題の種類全体を修正します。 ある呼び出し箇所でパラメーターが欠落していたなら、同様の呼び出し箇所をすべて grep します。あるエラーメッセージに誤りがあったなら、エラー表示全体を監査します。
• すべての修正に、修正前は失敗し、修正後は成功する回帰テストを付けます。 周辺コードをテストで実行するのが難しい場合は、テストなしよりも、コードの構造を検証するソースレベルの契約テストが優れています。
• 再発を防ぎます。 バグの種類によっては、気付かれないまま再発する可能性があります（誰かが削除するかもしれないフラグや、誰かが短縮するかもしれないタイムアウトなど）。失敗時のメッセージに元のインシデント名を含めるテストで固定します。
• 正しさと再発防止を両立する、最小限の変更にします。冗長さではなく、必要な手間をかけます。

マージ：雰囲気ではなくゲートで判断

• マージ時に評価する構造的なチェックで判断します。順番に確認したから問題ないと想定してはいけません。必須テストのチェックが合格し、マージ可能性がクリーンであることを確認します。一時的な不明状態はポーリングし、説明のつかない失敗がある状態では決してマージしません。
• 不安定な失敗か、本当の失敗か： 失敗したジョブを再実行する前に、無関係な PR が同一の失敗パターンに遭遇していないか確認します。無関係な差分で同じ失敗が起きているなら環境の不安定さです（1回だけ再実行します）。それ以外は、まず調査します。同じ不安定な失敗が3件以上の PR で再発した場合は、再実行をやめて、不安定さ自体の根本原因を特定します。断続的な CI の失敗は、通常、漏れ出したグローバル状態が原因です。漏れをリセットし、警告に状態を汚染したテスト名を記載するテストスイートのガードがあれば、見つけにくいハイゼンバグを grep 1回で修正できる問題に変えられます。
• パイプでつないだコマンドの終了コードを信用しません。 pytest | tail の終了ステータスは tail のものになります。マージやリリースの可否を左右する処理では、完全な出力をファイルに保存し、実際の $? を明示的に出力します。
• 委任した作業やエージェントの作業は、独立して検証します。差分を1行ずつ確認し、クリーンなブランチでテストを自分で再実行します。エージェント自身の成功報告を、自分で行った検証のように伝えてはいけません。
• 自動レビュー（CodeQL、ボットのレビュー）は実際に読みます。合格・不合格のステータスがレビューそのものではありません。緑のチェックマークの陰に重要な指摘が隠れていることがあります。マージ済み PR に対して指摘があった場合は、レビュー担当者にクレジットを付与し、マージ後のフォローアップとして対応します。

リリース

• バージョン関連のファイルを変更する前に、すべてのゲートを実行してください。 テストスイートの実行中にバージョンを更新したり、ロックファイルを再生成したりすると、状態が混在し、バージョン整合性テストの結果が損なわれます。
• バージョンのリテラルは単一の信頼できる情報源に置きます。ミラーも同時に更新し、テストで保護します。
• 変更履歴はタグ付け前にユーザー向けに作成します。 見出しの段落と、グループ分けした項目で構成します。各項目は、ユーザーが得られるものを示す太字の一行と、理由を平易な言葉で説明する1～3行、Issue／PRへの参照を含めます。自動生成したコミット一覧をリリースノートとして公開してはいけません。リリースへの貢献者には、本人のリリースであれば見出しで名前を挙げて謝意を示します。
• タグ付け後は、疑いの目でビルド済みリリースを確認します。アセット数、ドラフトではないこと、プレリリースではないこと、本文に実際に変更履歴の該当セクションが含まれていることを確認してください。
• リリースはトリアージの手段でもあります。公開済みでも未確認の修正は、ユーザーがビルドを入手できるまで確認されません。「次のバージョンを試す」必要のあるIssueが複数ある場合、リリースを行うこと自体がキューをさばく作業です。

コミュニケーション

• すべてのIssueとPRの作成者に、具体的に感謝します。 何がよかったのかを挙げてください。A/Bの再現手順、行単位の診断、動作するパッチなどです。一般的なお礼は、感謝していないのと同じように受け取られます。
• 結果を最初に伝え、誠実でいてください。 自分が間違っていたなら、「それは間違いでした」と正しい答えを伝えます。注意深い貢献者に誤りを指摘されたら、黙って編集するのではなく、明確に謝意を示してください。早まってクローズしたなら、曖昧にせず記録を正してください。
• クローズ後も再開できることを伝えるテンプレートでは、公開した内容、または対応できることがない理由を述べたうえで、会話を再開するために必要な具体的な資料（ログ、再現手順、バージョン）を示し、誠意を持って対応します。
• 古い報告については、説明のないIssueをクローズする前に、報告された手順を自分で試します（「現在のビルドで該当するコードパスをそのままテストしました。問題なく動作します。詳細を添えて再度開いてください」）。新しい証拠に基づくクローズは報告者への敬意を示しますが、何も伝えずに古いIssueをクローズするのはそうではありません。
• ドキュメントの更新も修正の一部です。変更によってドキュメントの記述内容が変わる場合、同じPRでドキュメントも更新します。また、誤りだと判明したドキュメント（たとえば、貢献者が後に修正したものを修正不可能と記載していた場合）は、貢献者への謝意を示して直ちに訂正します。

判断の基本方針

• 古いバージョンの報告では、詳細な調査に入る前に、関連する修正が含まれたバージョン以降へ更新するよう報告者に依頼します。古いバージョンの報告は、更新方法と再開できる旨を添えてクローズします。
• 理論より報告の証拠を優先します。貼り付けられたログは、どれほど有力な仮説よりも優先されます。十分な証拠に基づいて仮説を立てますが、ログで確認されるまでは、その仮説に基づくコードを公開してはいけません。また、どちらに取り組んでいるのかを明示します。
• ローカルでテストできないプラットフォーム固有の修正は、仕組みを検証し、そのプラットフォーム向けのコンパイル／テストをCIで確認したうえで公開します。制約事項をPRに明記し、報告者にエンドツーエンドのテストを依頼します。
• 上流の制約で修正できない場合は、上流のIssueへのリンクとユーザー向けの回避策を添えて記録します。「修正不可能」と書く前に、その主張が現在の上流ソースでも正しいことを改めて確認してください。