upstream-first

Upstream First スキル

このスキルは mgifford/upstream-firstへの案内です。これは、アクセシビリティ上の問題（またはその他の問題）に対する修正がどこに属するのかを判断し、受け入れ先のプロジェクトに提出できる状態に整えるための、独立したエージェントスキル集です。このスキルでは、そのプロジェクトの判断階層、分類手順、コントリビューションのワークフローを再掲しません。これらの内容は同プロジェクト側で管理され、このスキルがまだプレリリース審査中のドラフトであるプロジェクトと同期しなくなることを防ぎます。

使用するタイミング

アクセシビリティ上の障壁を修正する前に、影響を受けるコードが本当にこのプロジェクトの管轄かどうかを確認してください。

• 複数のプロジェクトで使われる共有コンポーネントまたはデザインシステム。
• レンダラー、フレームワーク、またはプラットフォームの依存関係。
• ファーストパーティのコードではなく、npm/PyPI/Packagist/Composer パッケージ。
• このプロジェクトだけでなく、同じ依存関係を利用する他のユーザーにも役立つパターン。

障壁の原因がこのプロジェクト自体のコード以外にある可能性がある場合は、 upstream-first を読み込み、責任ある修正が次のどれに当たるか判断してください。

1. 既にインストールされている機能。
2. 既存のパブリック API または拡張ポイント。
3. 適切に保守されているオープンソースパッケージ。
4. 既存プロジェクトへの対象を絞ったコントリビューション。
5. 信頼できる管理体制を備えた、新しい再利用可能なオープンソースパッケージ。
6. それより優先度の高いすべての選択肢が不適切である理由を文書化したうえでの、ローカル実装。

この判断を経ずに、ローカルのパッチをデフォルトの選択肢にしないでください。共有コンポーネントの障壁をローカルで修正すると、そのコンポーネントを利用する他のすべてのユーザーに同じ保守負担が繰り返し発生します。また、その障壁の影響を受けるのは、このプロジェクトのユーザーだけではありません。

コントリビューションの準備

上流へのコントリビューションが適切と判断された場合は、 maintainer-ready-contribution を使って、受け入れ先プロジェクトのメンテナーが実際にレビューして受け入れられる課題、提案、パッチ、またはプルリクエストを準備してください。

セキュリティ脆弱性の可能性がある場合は、公開課題、再現手順、ブランチ、フォーク、プルリクエストを作成しないでください。代わりに responsible-security-disclosure を使用してください。

既知のコントリビューションに AI が実質的に関与した場合は、受け入れ先プロジェクトのポリシーでその利用が許可されている場合、提出前に ai-contribution-review を実行してください。

人間の承認が必要です

人間が特定の操作を明示的に承認しない限り、外部プロジェクトで課題の作成やコメント、割り当て、ラベル付け、フォーク、ブランチの作成、提出を行わないでください。変更を上流に反映すべきだと判断することと、他者のプロジェクトでその判断に基づいて行動する権限を得ることは別です。

一時的なローカルの差異の追跡

上流で修正されるまでの間、緊急のローカルパッチ、オーバーライド、フォーク、固定、または回避策が必要になる場合があります。アクセシビリティ上の障壁は、プロジェクトが管理していないリリースを待つべきではありません。このような場合は、解決済みとして扱わないでください。負債として記録し、以下を明記してください。

• 下流側の担当者。
• 上流の参照先、または参照先がない場合は文書化された例外。
• リスクに基づくレビュー日。
• パッチが適用されるサポート対象バージョン。
• 削除条件（サポート対象の上流リリースを採用し、検証済みであること）。 および
• ロールバック計画。

このプロジェクトで ACCESSIBILITY.md テンプレートを使用している場合は、 下流の差異の記録 を使用してください。それ以外の場合は、 upstream-debt の記録形式 をそのまま使用してください。

上流のトラッカー項目がマージまたはクローズされても、解決したことにはなりません。 クローズするには、サポート対象のリリースを下流で採用し、元のユーザー向けの動作を再テストする必要があります。このスキーマで検出事項を追跡しているプロジェクトの場合は、 アクセシビリティ検出事項の追跡「ローカルおよび上流のトラッカー」 を参照してください。

他のスキルとの関係

• ACCESSIBILITY-general は、このリポジトリ内のすべてのスキルをいつ、どのように読み込むかを規定します。このスキルは、修正の担当箇所が不明な場合に、同スキルから参照される項目の一つです。
• bug-reporting は、報告された検出事項の範囲、原因として考えられる箇所、および（該当する場合）ローカルと上流のトラッカーの関係を記録します。このスキルでは、修正を記述した後ではなく、その原因に対して何をするかを決めます。
• トピック別スキル（forms、keyboard、color-contrast など）は、担当箇所が決まった後に、障壁をどのように修正するかを定義します。このスキルは、修正をどこに加えるかを決めます。

参考資料

• Upstream First
• AI時代に Upstream First が重要な理由
• upstream-first スキル
• maintainer-ready-contribution スキル
• ai-contribution-review スキル
• responsible-security-disclosure スキル
• ACCESSIBILITY.md：下流の差異の記録