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

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

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

Цільові PR

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

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

    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, що обробляється.

Підготовка

Виконуйте ці кроки з кореня локальної копії з налаштованим віддаленим репозиторієм 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 зазвичай є тимчасовим. Якщо перевірка посилань повідомляє про статус 5XX для URL, вважайте його ймовірно тимчасовим (сервер недоступний, помилки шлюзу, перевантаження). Не змінюйте вміст сайту або посилання лише для обходу 5XX; краще повторно запустіть npm run log:check:links пізніше. Досліджуйте 5XX як реальний дефект лише якщо він продовжує виникати протягом кількох запусків і ви підтвердили, що URL в іншому випадку не працює.

  1. Зберіть сайт і перевірте посилання: npm run log:check:links. Це також оновлює .lycheecache та зберігає журнал перевірки, який читає крок подвійної перевірки нижче. Див. примітку про LinkedIn нижче.

  2. Якщо перевірка проходить, завершіть PR.

  3. Інакше, перерахуйте невдалі URL та їх статуси з виводу перевірки (для запуску CI див. журнал невдалого завдання CHECK LINKS PR).

  4. Для збоїв, схожих на блокування ботів, а не на мертві посилання (наприклад, 403/429/999 із сайтів, які нормально завантажуються у вебоглядачі), повторно перевірте їх через реальний оглядач, перш ніж аналізувати:

    npm run fix:link-cache:double-check

    Проба читає журнал, збережений на кроці 1. URL, які проба підтверджує, кешуються; повторіть з кроку 1 та аналізуйте лише збої, що залишилися. Детальніше див. Подвійна перевірка невдалих посилань.

  5. Аналіз та рекомендації. Для кожного невдалого URL повідомте:

    • URL та HTTP-статус.
    • Звідки він походить: надайте посилання на файли або сторінки.
    • Рекомендоване виправлення або подальші дії; див. Рекомендації щодо виправлення невдалих URL.
    • Де належить виправлення, наприклад:
      • У гілці
      • В окремому PR проти main, коли те саме недійсне посилання також впливає на main або кілька цільових PR
      • Upstream у вихідному репозиторії, для гілок інтеграції

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

  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 навіть після squash-злиття.

  3. Якщо виклик навички не вимагає коментаря (наприклад, включає “без коментаря” або “тихо”), додайте коментар до PR (gh pr comment <num> --body '…'), що складається з:

    • Виклику навички, як вбудованого коду — відтвореного у мінімальній формі (назва навички та вибір цілі лише). Ніколи не цитуйте навколишню розмову, яка може містити приватний або не повʼязаний контекст.
    • Стислого, одно- або дворядкового підсумку виконання.

    Наприклад:

    Оновлення 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

Обґрунтовуйте кожну рекомендацію доказами та підбирайте виправлення відповідно до ситуації:

  • Повʼязана сторінка переміщена: оновіть посилання, з доказами, що заміна відповідає призначенню.
  • Субʼєкт запису зник: коли посилання походить із запису реєстру або списку екосистеми: adopters, distributions, integrations, vendors, і компонент, продукт або компанія за записом припинили існування, були поглинуті або іншим чином більше не підтримують OpenTelemetry, вилучіть запис замість оновлення його посилань.
  • Повʼязана сторінка зникла, еквівалента немає: Агенти не повинні застосовувати це виправлення; передайте підтримувачу. Як крайній засіб, підтримувач може видалити посилання та переробити навколишній текст. За потреби додайте в копію нікнейми GitHub:
    • Авторів PR, які додали вміст
    • Затверджувачів SIG docs через їхній нікнейм команди GitHub

Докази для URL заміни

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

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

Вилучення запису

Востаннє змінено July 12, 2026: [uk] Ukrainian documentation for OpenTelemetry (4cc17d8b)