# Refresh-link-cache PR の修正

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

---

LLMS index: [llms.txt](/llms.txt)

---

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

## 対象 PR {#target-prs}

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

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

   ```sh
   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 のヘッドブランチを指します。

## 準備 {#preparation}

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

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

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

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

## 5XX レスポンスの処理 {#handling-5xx-responses}

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

## 失敗したリンクの解決 {#resolve-failing-links}

1. サイトをビルドしてリンクをチェックします: `npm run log:check:links`。
   これにより `.lycheecache` も更新され、以下のダブルチェック手順で読み取るチェックログがキャプチャされます。
   下記の LinkedIn に関する注意事項を参照してください。
2. チェックが成功した場合は、[PR のまとめ](#wrap-up)に進みます。
3. **それ以外の場合は**、チェック出力から失敗した URL とそのステータスを一覧表示します（CI 実行の場合は、PR の失敗した `CHECK LINKS` ジョブのログを参照）。

   > [!NOTE] LinkedIn の URL
   >
   > `LinkedIn.com` からのレスポンスはしばしば信頼性に欠けます（エージェントやボットはプロフィールが存在していても 403、404、999 を受け取ることがあります）。
   > そのようなステータスで LinkedIn のリンクを削除や編集**しないでください**。
   > 代わりにメンテナーに手動で検証してもらいます。

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

   ```sh
   npm run fix:link-cache:double-check
   ```

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

5. **分析と推奨**。
   失敗した各 URL について、以下を報告します。
   - URL と HTTP ステータス。
   - 発生元: ファイルやページへのリンクを提示します。
   - 推奨する修正またはフォローアップアクション。
     [失敗した URL の修正を推奨する](#recommending-a-fix-for-failing-urls)を参照してください。
   - 修正の適用先。たとえば:
     - ブランチ内
     - 同じデッドリンクが `main` や複数の対象 PR にも影響する場合は、`main` に対する別の PR
     - 統合ブランチの場合はソースリポジトリの上流

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

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

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

   ```sh
   npm run fix:i18n:status -- PATHS_TO_FAILING_LOCALIZED_PAGES
   ```

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

## まとめ {#wrap-up}

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

1. リンクチェックの概要を返信で共有します（再チェックまたは修正された URL、および表示された場合は最終的なステータスカウント）。
2. `.lycheecache` が変更された場合は、upstream の _`TARGET_BRANCH`_ にコミットしてプッシュします。
   コミットメッセージの本文にはリンクチェックの概要を使用します（プレーンテキスト。URL リストが長い場合はカウントのみを含めます）。
   これはスカッシュマージ後も PR のコミット履歴に残ります。
3. スキルの呼び出しでコメント不要と指定されていない限り（たとえば "no comment" や "silent" を含む場合）、PR にコメントを追加します（`gh pr comment <num> --body '…'`）。
   内容は以下のとおりです。
   - スキルの呼び出しをインラインコードとして記載します。
     最小限の形式（スキル名と対象の選択のみ）で再構成します。
     周囲の会話は引用しないでください。
     プライベートな情報や無関係なコンテキストが含まれている可能性があります。
   - 実行の簡潔な1〜2行の要約。

   たとえば:

   ```text
   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 の修正を推奨する {#recommending-a-fix-for-failing-urls}

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

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

### 置き換え URL の証拠 {#evidence-for-a-replacement-url}

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

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

### エントリの廃止 {#retiring-an-entry}

- エントリを削除します。
- PR コメントで、エントリの最初の提出者やエントリを更新した作成者の GitHub ハンドルを Cc します。
  [レジストリとリスト情報を最新に保つ](/ecosystem/registry/updating/)を参照してください。

<!-- prettier-ignore-start -->
[drift status]: /docs/contributing/localization/#drift-status
[link fixes and resource updates]:
  /docs/contributing/localization/#link-fixes-and-resource-updates
<!-- prettier-ignore-end -->