# PR виправлення оновлення link-cache

> Як вирішити проблеми з невдалими перевірками посилань у PR від otelbot.

---

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

---

Виконайте ці кроки, щоб вирішити проблеми з невдалими перевірками посилань у [цільових PR від otelbot](#target-prs). Цей процес може включати оновлення або видалення недійсних посилань на сайті, а потім повторну перевірку посилань, поки не залишиться жодної помилки.

## Цільові PR {#target-prs}

Зазвичай обробляються всі відкриті PR від otelbot — ті, чия головна гілка відповідає `otelbot/*`. Якщо вказано, звузьте обробку до названої гілки або групи гілок (наприклад, `otelbot/refcache-refresh` або гілки інтеграції spec/semconv); запитайте, якщо інструкція неоднозначна. Ця навичка працює з PR: якщо названа гілка не має відкритого PR, повідомте про це та зупиніться.

1. Перелічіть відкриті PR від otelbot:

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

2. Визначте, які з них мають невдалі перевірки посилань — перевірки робочого процесу `Links` (`gh pr checks <num>`).
3. Повідомте результати оцінки **перед обробкою будь-якого PR**: один рядок на PR — номер, головна гілка, статус чернетки, чи буде він оброблений (з причиною, якщо пропущено).
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 зазвичай є тимчасовим. Якщо перевірка посилань повідомляє про статус 5XX для URL, вважайте його ймовірно тимчасовим (сервер недоступний, помилки шлюзу, перевантаження). **Не змінюйте** вміст сайту або посилання лише для обходу 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 див. журнал невдалого завдання `CHECK LINKS` PR).

   > [!NOTE] URL LinkedIn
   >
   > Відповіді з `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).
   - Де належить виправлення, наприклад:
     - У гілці
     - В окремому PR проти `main`, коли те саме недійсне посилання також впливає на `main` або кілька цільових PR
     - Upstream у вихідному репозиторії, для гілок інтеграції

   Зупиніться та зачекайте затвердження рецензента — ніколи не затверджуйте рекомендації самостійно.

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 навіть після squash-злиття.
3. Якщо виклик навички не вимагає коментаря (наприклад, включає "без коментаря" або "тихо"), додайте коментар до PR (`gh pr comment <num> --body '…'`), що складається з:
   - Виклику навички, як вбудованого коду — відтвореного у мінімальній формі (назва навички та вибір цілі лише). Ніколи не цитуйте навколишню розмову, яка може містити приватний або не повʼязаний контекст.
   - Стислого, одно- або дворядкового підсумку виконання.

   Наприклад:

   ```text
   Оновлення link-cache виконано за допомогою: `/refresh-link-cache-pr-fix for the collector-docs branch`

   Повторно перевірено невдалі URL; всі тепер доступні — перевірка посилань проходить.
   ```

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), що заміна відповідає призначенню.
- **Субʼєкт запису зник**: коли посилання походить із запису реєстру або списку екосистеми: adopters, distributions, integrations, vendors, і компонент, продукт або компанія за записом припинили існування, були поглинуті або іншим чином більше не підтримують OpenTelemetry, [вилучіть запис](#retiring-an-entry) замість оновлення його посилань.
- **Повʼязана сторінка зникла, еквівалента немає**: Агенти не повинні застосовувати це виправлення; передайте підтримувачу. Як крайній засіб, **підтримувач** може видалити посилання та переробити навколишній текст. За потреби додайте в копію нікнейми GitHub:
  - Авторів PR, які додали вміст
  - Затверджувачів SIG docs через їхній нікнейм команди GitHub

### Докази для URL заміни {#evidence-for-a-replacement-url}

Покажіть, що отримана сторінка відповідає назвою або іншим чином відповідає повʼязаному ресурсу:

- Статус 2XX сам по собі нічого не доводить: SPA-перехоплювачі та сторінки входу повертають 200 для будь-якого шляху.
- Для посилань на github.com заміну слід здійснювати на основі останнього коміту, що містить зазначений ресурс.
- [Wayback Machine](https://web.archive.org/) може показати, що раніше знаходилося за недійсним URL або куди він перемістився; перевірте коротко, але не заглиблюйтесь, якщо не просять — архів повільний.

### Вилучення запису {#retiring-an-entry}

- Вилучіть запис
- Додайте в коментарі PR нікнейми оригінального автора запису та/або авторів, які оновлювали запис, відповідно до [Підтримка актуальності реєстру та списків](/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 -->