Refresh-link-cache PR の修正

otelbot の PR で失敗するリンクチェックを解決する方法。

以下の手順に従って、対象の otelbot PR で失敗するリンクチェックを解決します。 このプロセスでは、サイト上のデッドリンクを更新または削除してから、失敗がなくなるまでリンクチェックを再実行することがあります。

対象 PR

デフォルトでは、ヘッドブランチが otelbot/* に一致するすべてのオープンな otelbot PR を対象とします。 指示がある場合は、指定されたブランチまたはブランチグループ（たとえば otelbot/refcache-refresh や spec/semconv の統合ブランチ）に範囲を絞ります。 指示が曖昧な場合は確認してください。 このスキルは PR を対象に操作します。 指定されたブランチにオープンな PR がない場合は、その旨を報告して停止します。

  1. オープンな otelbot PR を一覧表示します。

    gh pr list --search head:otelbot/ --json number,title,headRefName,isDraft

  2. そのうちどれがリンクチェックに失敗しているかを判定します。 Links ワークフローのチェック（gh pr checks <num>）を確認します。

  3. いずれかの PR を処理する前に、対象評価を報告します。 PR ごとに1行で、番号、ヘッドブランチ、ドラフト状態、処理対象かどうか（スキップする場合はその理由）を示します。

  4. 条件を満たす各 PR を順に処理し、以下のセクションに従います。 処理を開始する際に PR を明示してください。 これらの手順では、TARGET_BRANCH は処理中の PR のヘッドブランチを指します。

準備

ローカルクローンのルートから以下の手順を実行します。 upstream リモートがメインリポジトリを指している必要があります。

  1. PR ブランチをチェックアウトします: gh pr checkout <num>。 ローカルの TARGET_BRANCH が分岐しているために失敗する場合は、ローカルのみのコミットをバックアップ（または停止）してから、再整合します。

    git fetch upstream
git checkout TARGET_BRANCH
git reset --hard upstream/TARGET_BRANCH

  2. コンテンツモジュールが古い場合は、npm run get:submodule を実行します。

5XX レスポンスの処理

ステータス 5XX のレスポンスは通常一時的なものです。 リンクチェックが URL に対してステータス 5XX を報告した場合は、一時的なもの（オリジンのダウン、ゲートウェイエラー、過負荷）として扱います。 5XX を回避するためだけにサイトのコンテンツやリンクを変更しないでください。 後で npm run log:check:links を再実行することを推奨します。 5XX を実際の欠陥として調査するのは、複数回の実行にわたって繰り返し失敗し、URL が正常でないことを確認した場合のみです。

  1. サイトをビルドしてリンクをチェックします: npm run log:check:links。 これにより .lycheecache も更新され、以下のダブルチェック手順で読み取るチェックログがキャプチャされます。 下記の LinkedIn に関する注意事項を参照してください。

  2. チェックが成功した場合は、PR のまとめに進みます。

  3. それ以外の場合は、チェック出力から失敗した URL とそのステータスを一覧表示します（CI 実行の場合は、PR の失敗した CHECK LINKS ジョブのログを参照）。

  4. ボットブロックのように見える失敗（たとえば、ブラウザでは正常に読み込まれるサイトからの 403/429/999）については、分析する前に実際のブラウザで再検証します。

    npm run fix:link-cache:double-check

    プローブは手順1でキャプチャされたログを読み取ります。 プローブがクリアした URL はキャッシュされます。 手順1から繰り返し、残った失敗のみを分析します。 詳細については、失敗したリンクのダブルチェックを参照してください。

  5. 分析と推奨。 失敗した各 URL について、以下を報告します。

    • URL と HTTP ステータス。
    • 発生元: ファイルやページへのリンクを提示します。
    • 推奨する修正またはフォローアップアクション。 失敗した URL の修正を推奨するを参照してください。
    • 修正の適用先。たとえば:
      • ブランチ内
      • 同じデッドリンクが main や複数の対象 PR にも影響する場合は、main に対する別の PR
      • 統合ブランチの場合はソースリポジトリの上流

    停止してレビュアーの承認を待ちます。 推奨を自己承認しないでください。

  6. 承認された修正を適用します。 メンテナーが承認した修正とフォローアップアクションのみを実行します。 content/ 以下のページコンテンツについては、英語ページのみを編集します。 ローカライズされたページのコンテンツは決して編集しないでください。

  7. ソースリンクの変更後、npm run log:check:links を実行してリンクを再チェックし .lycheecache を更新します。 ローカライズされたページがまだ失敗する場合は、編集するかわりにドリフトステータスを更新します。

    npm run fix:i18n:status -- PATHS_TO_FAILING_LOCALIZED_PAGES

    まれに、ローカライズされたページにのみ存在する失敗したリンクがある場合は、報告してそのロケールチームと修正を調整します。 詳細については、リンクの修正とリソースの更新を参照してください。 チェックが成功するまで、このセクションの手順（手順2から）を繰り返します。

まとめ

処理中の PR でリンクチェックが成功したら:

  1. リンクチェックの概要を返信で共有します（再チェックまたは修正された URL、および表示された場合は最終的なステータスカウント）。

  2. .lycheecache が変更された場合は、upstream の TARGET_BRANCH にコミットしてプッシュします。 コミットメッセージの本文にはリンクチェックの概要を使用します（プレーンテキスト。URL リストが長い場合はカウントのみを含めます）。 これはスカッシュマージ後も PR のコミット履歴に残ります。

  3. スキルの呼び出しでコメント不要と指定されていない限り（たとえば “no comment” や “silent” を含む場合）、PR にコメントを追加します（gh pr comment <num> --body '…'）。 内容は以下のとおりです。

    • スキルの呼び出しをインラインコードとして記載します。 最小限の形式（スキル名と対象の選択のみ）で再構成します。 周囲の会話は引用しないでください。 プライベートな情報や無関係なコンテキストが含まれている可能性があります。
    • 実行の簡潔な1〜2行の要約。

    たとえば:

    Link-cache update done using: `/refresh-link-cache-pr-fix for the collector-docs branch`

Re-checked the failing URLs; all now resolve -- the link check passes.

  4. PR がドラフトでなく、リンクチェックが唯一の失敗しているチェックであった場合は、オートマージを有効にし（gh pr merge <num> --auto --squash）、オートマージが完了するようにメンテナーに PR の承認をリマインドします。 PR へのリンクを含めてください。 それ以外の場合は、PR をそのままにした理由を報告します。 ドラフト状態（たとえば、リリース時に独自のワークフローで最終化される統合 PR）やその他の失敗しているチェックなどです。

次の対象 PR がある場合は、続けて処理します。

失敗した URL の修正を推奨する

すべての推奨を証拠に基づいて行い、状況に合った修正を選択します。

  • リンク先のページが移動した場合: リンクを更新します。 置き換え先が一致することを示す証拠を添えます。
  • エントリの対象がなくなった場合: リンクがレジストリやエコシステムリストのエントリ（アダプター、ディストリビューション、インテグレーション、ベンダー）から発生しており、エントリの背後にあるコンポーネント、製品、または企業が廃止、吸収、またはその他の理由で OpenTelemetry のサポートを積極的に行っていない場合は、リンクを更新するかわりにエントリを廃止します。
  • リンク先のページが存在せず、同等のものがない場合: エージェントはこの修正を適用してはなりません。 メンテナーに委ねてください。 最終手段として、メンテナーがリンクを削除し、周囲の文章を書き直すことがあります。 必要に応じて以下の GitHub ハンドルを Cc します。
    • コンテンツを導入した PR の作成者
    • GitHub チームハンドルを通じた SIG docs の承認者

置き換え URL の証拠

取得したページがリンク先のリソースと名前またはその他の方法で一致することを示します。

  • 2XX ステータスだけでは証明になりません。 SPA のキャッチオールやログインページは、任意のパスに対して 200 を返します。
  • github.com へのリンクの場合は、対象のリソースを含む最後のコミットに基づいて置き換えを行います。
  • Wayback Machine を使用すると、デッドな URL が以前何を提供していたか、どこに移動したかを確認できます。 簡単に確認しますが、依頼されない限り深く調査しないでください。 アーカイブは低速です。

エントリの廃止

最終更新 August 9, 2026: [ja] add translation of content/en/site/skills/refresh-link-cache-pr-fix.md (#11252) (74d8cb2a)