ダウンストリームフォークのメンテナンス
概要
ダウンストリームフォークを維持する目的は、上流から徐々に乖離して独立したハードフォークに発展させることではありません。目的は、常に使用可能で、ビルド可能、テスト可能な状態を維持する一連のパッチを継続的に管理することです。
ダウンストリームは上流に追従しつつ、PRがまだマージされていない、上流のメンテナが多忙である、またはパッチがニッチながら緊急である場合に、これらの機能と修正を含むコードとアーティファクトをユーザーに迅速に提供します。これは静的なパッチアーカイブではなく、パッチが実際に実行され、検証を受け続ける配布チャネルです。
使用可能な統合結果は、より多くの人々が上流のPR、ダウンストリームのパッチ、および自身の変更を自由にテストできるようにもします。上流が前進するにつれて、パッチを継続的にビルド、テスト、レビューすることで、PRが上流に遅れて腐るリスクを低減し、問題を早期に発見し、最終的に変更が上流に還流するのに役立ちます。
コア目標
- ダウンストリームフォークが上流から分離したハードフォークになるのを防ぐ。
- ある時点の静的なブランチのみを保存するのではなく、継続的に上流に追従する。
- すべてのパッチを独立してビルド可能、テスト可能、レビュー可能、そして提出または継続的なPRメンテナンスに適した状態に保つ。
- メインブランチまたはリリースブランチを通じて、直接使用可能なコードとアーティファクトを提供する。
- ユーザーが実際の統合結果に対してPR、パッチ、および自身の変更をテストできるようにする。
- パッチと上流の間の競合を早期に検出し、PRのマージ可能性を維持し、パッチが上流に還流するのを支援する。
ブランチモデル
リポジトリが実際のブランチ名を決定します。デフォルトブランチ、リモート名、またはホスティングプラットフォームを想定しないでください。
上流メインブランチ
上流メインブランチは、すべてのリビルドの開始点です。同期の前にその最新状態をフェッチし、現在のビルドのベースラインとして特定の上流コミットを使用します。
ダウンストリームのメインまたはリリースブランチが、パッチの新しいベースラインになってはいけません。パッチは常に、上流に対して何を変更するかを明確に示す必要があります。
パッチブランチ
各独立したパッチを独自のブランチで維持し、通常のPR基準を適用します：
- スコープを絞り、コミットと説明を明確に保つ。
- 動作を示すのに十分なテストを含める。
- 現在の上流上で独立してビルド可能かつレビュー可能にする。
- 必要な依存関係のみを宣言し、他のダウンストリームパッチに結び付けない。
- 上流PRとして直接提出するか、既存のPRの継続メンテナンスに適したものにする。
- 一般に、パッチブランチは
CHANGELOGなど、上流メンテナが中央管理するリリースファイルを変更すべきではありません。必要なドキュメント変更は、コードコメント、APIドキュメント、およびそのパッチに直接関連する実装ノートに限定します。ダウンストリームのパッチリストとリリースノートは、メンテナンスブランチ上で集中的に管理します。
パッチブランチは、そのパッチの長期的な信頼できる情報源です。リリースブランチ上の統合コミットは、そのパッチの唯一のコピーではなく、リリース履歴にのみ存在する一時的な修正を保持してはいけません。
一時的な互換性パッチブランチ
複数のパッチが独立して適用されるが、組み合わせたときに、個々のPRブランチに属さないビルド、テスト、または動作の競合が発生する場合は、tmp/patch/<name>ブランチで互換性パッチを維持します。
そのようなブランチは、特定のパッチ組み合わせのダウンストリーム互換性問題のみに対処します。独立したPRブランチのいずれかに修正を強制せず、新しい長期機能ブランチにしないでください。どのパッチに依存するか、どの順序に属するか、どの組み合わせ動作を検証するか、いつ廃止できるかを明記する必要があります。
ciブランチ上の同期オーケストレーションで、tmp/patch/<name>を依存するパッチの直後に順序付けして追加します。以前のGitマージですでに未解決のテキスト競合が発生している場合、後続の互換性ブランチはその競合を越えることができません。その場合、ciオーケストレーションは、リビルドを続行する前に、競合が発生したステップで対応する互換性処理を明示的に適用する必要があります。単にブランチをリストの最後に追加するだけでは不十分です。
メンテナンスブランチ ci
フォークがGitHub Actionsなどの自動化を実行する必要がある場合、個別のciブランチを維持します。リポジトリに同等のブランチがすでに存在する場合は、その名前を保持します。このブランチはダウンストリームフォークのリリースオーバーレイであり、以下を担当します：
- ダウンストリーム固有のCI/CD、パッケージング、リリース、およびリポジトリ設定。
- 上流の自動フェッチ、パッチの順序通りの統合、リリースブランチのリビルド、および安全なプッシュ。
- 追加のダウンストリーム単一パッチテストおよびマルチパッチ統合テスト。
- ダウンストリームのREADME、パッチリスト、リリースノート、およびダウンストリーム固有のメンテナンス手順。
- 有効な通常パッチと
tmp/patch/<name>ブランチの固定された統合順序。
ユーザーまたはダウンストリームフォークにこの一般的なワークフローを超えるメンテナンス要件がある場合は、ciブランチ上のダウンストリーム所有のMAINTAIN.mdに保持します。この特定のフォークをどのように維持する必要があるかを記載し、将来のメンテナと自動化が従うべき特別なルールを記録する必要があります。これをリポジトリ固有のガイダンスとして扱います：パッチブランチ、同期オーケストレーション、またはリリース履歴を変更する前にこれを読み、それらの要件が変更されたときに最新の状態に保ちます。
特別なメンテナンスルールが見落とされる可能性がある場合は、ciブランチのREADME.mdに簡潔な注意事項を追加し、MAINTAIN.mdにリンクします。詳細なルールはREADMEに複製するのではなく、MAINTAIN.mdに保持します。
ciブランチは集中的にダウンストリームリリース自動化を実行してもかまいませんが、製品動作パッチを混入しないでください。ランタイムの変更は、独立したビルド、テスト、および上流PR提出に適したブランチに残す必要があります。
このスキルには、現在の実践で使用されているGitHub Actionsファイルが含まれています：ref/upstream-sync.yml。GitHub自動同期が必要な場合は、それを.github/workflows/upstream-sync.ymlの開始点としてコピーし、上流アドレス、デフォルト/リリースブランチ、ciおよびパッチリスト、tmp/patch/<name>の順序、同期スケジュール、ダウンストリーム所有ファイル、シークレット、およびターゲットリポジトリのチェックを適応させます。このファイルは元のプロジェクトからプロジェクト固有の設定を保持しているため、レビューなしで有効にしてはいけません。
scheduleを設定するときは、まずユーザーに毎日何時に同期を実行するかを尋ねます。GitHubのcronは、ワークフローがサポートされているtimezoneを明示的に設定しない限り、デフォルトでUTCを使用します。ジョブを時間の0分にスケジュールしないでください：GitHubの公式ドキュメントによると、毎時の開始時に負荷が高いため、スケジュールされたジョブは遅延したり、十分に高い負荷の下ではドロップされる可能性があります。一般的な5分刻みをさらに避けるために、10、15、20、30、40、45などの5の倍数を使用しないでください。1〜59の間で5の倍数ではない分をランダムに選択し、固定値としてワークフローに記述します。例えば、python -c 'import secrets; print(secrets.choice([m for m in range(1, 60) if m % 5]))'を実行します。ここでの「ランダム」は設定の生成時にのみ適用されます。ワークフローが実行ごとに動的なランダム遅延を待機するようにしないでください。
メインまたはリリースブランチ
メインまたはリリースブランチは、最新の上流から開始し、メンテナンスブランチと必要なパッチブランチを固定の順序で統合します。完全なコード、ビルド、テスト、およびリリースアーティファクトを提供します。
このブランチは現在のダウンストリーム統合結果のみを表します。どのパッチの長期的なメンテナンスソースでもありません。問題は最初にここで再現および分析されるかもしれませんが、修正は所有するパッチまたはメンテナンスブランチに戻す必要があり、その後統合結果を再生成する必要があります。
リリース履歴では、各パッチは明確でカウント可能な1つの統合コミットとして表示されるべきであり、ダウンストリームパッチの数とフォークが上流に遅れているコミット数の両方が見えるようにします。
ワークフロー
1. 現在の状態を調査する
開始する前に、リポジトリ自身のメンテナンスおよびコントリビューション手順、存在する場合はダウンストリームのMAINTAIN.md、およびそれを指すREADMEの注意事項を読みます。ワークツリー、リモート、現在のブランチ、上流との関係、および既存の同期およびリリースプロセスを調査します。コミットされていないユーザーの作業を保存または回避し、許可なしにクリーンアップまたは上書きしないでください。
2. コーディング前に上流の課題とプルリクエストを確認する
新しいリクエストを実装したりコードを書いたりする前に、上流の課題トラッカーとプルリクエストで関連する議論や実装を検索します。オープンおよびクローズされた課題、およびオープン、ドラフト、クローズ、マージされたPRを確認します。リクエストの正確な表現だけでなく、関連するコンポーネント名、エラーメッセージ、および適切な同義語も検索します。リンクされた課題、レビュー、コミット、および置換PRを十分に追跡して、現在のステータスを確立します。
結果を使用して次のアクションを選択します：
- 上流がすでに要件を実装している場合は、該当するバージョンと動作を確認してから、ダウンストリームの変更がまだ必要かどうかを判断します。
- アクティブな課題またはPRがそれをカバーしている場合は、認識しない重複を作成するのではなく、その作業に貢献、テスト、更新、または一時的に保持することを優先します。
- 以前のアプローチが却下、取り消し、または置き換えられた場合は、新しい実装を提案する前にその理由を理解します。
- 関連する上流リンクと結論を作業計画、パッチノート、またはPR説明に記録し、決定がレビュー可能なままになるようにします。
関連する上流の課題やPRが存在する場合、直接実装に進まないでください。まずそれらの実際のステータス、スコープ、決定、未解決の懸念事項、レビューフィードバック、実装状態、およびユーザーのリクエストとの関係を確立します。次に、上流情報の生のリンクリストを転送するのではなく、関連する上流情報をユーザーに統合して提示します。何が学ばれたか、それが現在の前提と計画にどのように影響するか、元のリクエストのどの部分がまだ必要かを明確に説明します。
その調査が、作業のスコープ、アプローチ、優先順位、所有権、互換性戦略、または必要性を変更する可能性のある新しい発見を生み出した場合は、明示的にユーザーに計画を変更すべきかどうかを尋ねます。ユーザーが計画を保持するか修正するかを確認するまで実装を一時停止します。上流の議論に基づいてリクエストを黙って再解釈しないでください。
1つの正確な用語検索で結果が返ってこなかったという理由だけで実装を開始しないでください。まず妥当な検索を実行します。関連する議論や実装が見つからない場合は、その結果を述べて続行します。
3. 完全な統合結果上で再現する
最初に、現在のメインまたはリリースブランチ上で問題を再現し、ユーザーが実際に実行するパッチの組み合わせでどのように発生するかを確認します。
分析中は、以下を区別します：
- 上流自体の問題。
- 1つの独立したパッチの問題。
- パッチ間の統合問題。個々のPRに属さない場合は、
tmp/patch/<name>に配置します。 - CI、パッケージング、同期、またはダウンストリームドキュメントの問題。
4. 所有ブランチを特定して修正する
動作の原因となっているパッチブランチを見つけ、そのブランチで修正とテストを完了します。問題が複数のパッチ間の互換性に関するものである場合は、tmp/patch/<name>を作成または更新します。リリース自動化またはその他のダウンストリームメンテナンス作業に関するものである場合は、ciブランチを変更します。
競合修正や製品修正をメインまたはリリースブランチのみにコミットしないでください。それは上流からの次のリビルドで失われ、パッチが独立してレビューされるのを防ぎます。
5. パッチを独立して使用可能に保つ
リポジトリの規約に従い、パッチを最新の上流に更新し、パッチブランチ上で競合を解決し、そのパッチに必要なビルドとテストを実行します。
リリースブランチの隠れた変更に依存しておらず、単独でPRとして説明、レビュー、提出できることを確認します。上流PRがすでに存在する場合は、それも更新し、上流からのフィードバックに応じて継続的にメンテナンスします。
6. メインまたはリリースブランチをリビルドする
最新の上流を再度フェッチし、特定の上流ヘッドからクリーンな候補ブランチを作成し、ciブランチによって宣言された固定順序でリリースオーバーレイ、通常パッチ、および必要なtmp/patch/<name>ブランチを統合します。
各通常パッチおよび一時的な互換性パッチは、リリース履歴に独自の明確な統合コミットを生成する必要があります。リポジトリはスカッシュマージまたはプロジェクトによって確立された同等の方法を使用してもかまいませんが、結果はレビューおよびカウントしやすいものにする必要があります。
7. 使用可能な結果を検証する
完全な候補バージョンに対してリポジトリの必須チェックを実行し、少なくとも以下をカバーします：
- 各パッチ自体に焦点を当てたテスト。
- 複数のパッチを組み合わせた後の統合動作。
- CI、パッケージング、およびダウンストリームドキュメントが正しいブランチから来ているか。
- ユーザーが実際に取得するコードまたはアーティファクトが検証されたコミットに対応しているか。
候補コードとアーティファクトの両方がすべての必須検証に合格した後にのみ、リモートのメインまたはリリースブランチを更新します。
自動同期
自動同期の目的は、新しい上流ヘッドから使用可能なダウンストリームリリース結果を定期的に再生成することであり、古いリリースブランチに修正を蓄積し続けることではありません。
同期プロセスは以下のようにします：
- リポジトリの許容された並行性制御を使用して、2つの同期またはリリースプロセスが同時に同じブランチを更新しないようにします。
- 最新の上流、
ciブランチ、すべての有効な通常パッチ、およびすべてのtmp/patch/<name>ブランチをフェッチします。 - その実行のために明示的に選択された上流コミットからクリーンな候補ブランチを作成します。
- ダウンストリームリリースオーバーレイ、通常パッチ、および一時的な互換性パッチを
ciブランチで宣言された順序で統合します。
セキュリティとプライバシーに関する注意事項
このスキルは上流リポジトリの公開情報にアクセスします（例：課題、PR、コミット）。ダウンストリームフォークが機密情報を含む場合、自動同期ワークフローでシークレットやアクセストークンを適切に管理する必要があります。パッチブランチに機密データをコミットしないでください。