Патчі вмісту модулів

Створення та керування тимчасовими патчами для модулів вмісту між релізами.

Сторінки Spec, опубліковані на сайті (OTel specification, OTLP, semantic conventions, OpAMP) походять з інших репозиторіїв, які керуються як git submodules в content-modules/. Оскільки сайт фіксує конкретний випуск кожного модуля, сирцевий Markdown є знімком, який можна оновити лише шляхом підвищення до нового випуску.

Коли відбувається запуск npm run cp:spec, cp-pages.sh копіює вміст submodule в tmp/, змінює назву файлів README.md на _index.md, та запускає adjust-pages.pl для кожного файлу Markdown. Hugo монтує tmp/ в дерево сайту тож оброблені сторінки зʼявляються у /docs/specs/.

Що робить скрипт

Файли Markdown Spec створенні для рендерингу на GitHub: вони не мають Hugo front matter, їх посилання вказують на GitHub URLs, а шляхи зображень орієнтуються на структуру їх репозиторіїв. Скрипт adjust-pages.pl наводить містки для заповнення цієї прогалини, виконуючи перетворення кожного файлу:

  • Додавання front matter — Видобуває перший заголовок # Heading і додає його в title, створює linkTitle, створює Hugo front matter. Підтримує front matter, вбудований в блоки коментарів <!--- Hugo ... --->.
  • Додавання версій — Додає версію специфікації (напр., 1.54.0) до titles та linkTitles для OTel spec, OTLP, та semconv сторінок.
  • Конвертування URL — Перетворює абсолютні шляхи GitHub URLs в репозиторіях spec на локальні шляхи /docs/specs/... тож перехресні посилання між специфікаціями працюють на сайті.
  • Шляхи зображень — Переписує відносні шляхи до зображень, щоб вони правильно розпізнавалися з місця розташування сторінки Hugo.
  • Очищення вмісту — Вилучення блоків <details> та розділів <!-- toc --> які не потрібні на сайті.
  • Тимчасові патчі — Застосовує виправлення на основі регулярних виразів для проблем зі специфікаціями, які ще не були виправлені у випуску (див. нижче).

Версії Spec вказуються вгорі скрипту в хеші %versionsRaw та оновлюються автоматично відповідним робочим процесом.

Патчі специфікацій між випусками

Виправлення несправного посилання або неправильного вмісту в специфікації вимагає PR до репозиторію верхнього рівня, нового випуску та оновлення підмодуля в цьому репозиторії. Цей процес може зайняти тижні або місяці. Тим часом несправний вміст спричиняє збої CI — найчастіше в автоматизованих PR otelbot/refcache-refresh, які перевіряють кожне зовнішнє посилання на сайті.

Щоб розблокувати CI, не чекаючи на випуску висхідного коду, ви можете додати тимчасовий патч до adjust-pages.pl. Патчі — це перевизначення на основі регулярних виразів, які виконуються під час побудови та містять вбудоване відстеження версій: як тільки специфікація перевищує діапазон версій патчу, cp:spec виводить попередження про те, що патч застарів і його можна видалити.

1. Додавання патчу

Патчі визначаються в масиві @patches на початку скрипту. Кожен запис є хешем з метаданими та підпрограмою apply. Додайте новий запис до масиву:

my @patches = (
  # ... наявні патчі ...
  {
    # Для проблемних посилань див.:
    # https://github.com/open-telemetry/semantic-conventions/issues/3103
    #
    # Замінити старі версії Docker API на останню:
    # https://github.com/open-telemetry/semantic-conventions/pull/3093
    id      => '2025-11-21-docker-api-versions',
    module  => 'semconv',
    minVers => '1.39.0-dev',
    maxVers => undef,
    file    => qr|^tmp/semconv/docs/|,
    apply   => sub {
      s{
        (https://docs.docker.com/reference/api/engine/version)/v1.(43|51)/(\#tag/)
      }{$1/v1.52/$3}gx;
    },
  },
);

Поля для кожного запису патча:

  • id — Унікальний ідентифікатор (дата + короткий опис), який виводиться в логах.
  • module — Один з spec, otlp або semconv.
  • minVers — Включно нижня межа. Патч застосовується, поки версія субмодуля дорівнює або перевищує цю версію, і стає застарілим, коли специфікація перевищує діапазон версій патча.
  • maxVers — Необовʼязкова виключна верхня межа. Якщо пропущено або встановлено undef, зазвичай використовується minVers з збільшеним номером патча (наприклад, 1.55.0 означає maxVers = 1.55.1), що відповідає оригінальній поведінці префіксного збігу. При явному встановленні патч пропускається, коли версія субмодуля досягає maxVers (тобто застосовується лише тоді, коли версія < maxVers).
  • file — Необовʼязковий скомпільований регулярний вираз, що відповідає шляхам файлів, до яких слід застосувати патч, наприклад qr|^tmp/semconv/docs/|. Якщо пропущено, зазвичай використовується дерево spec/docs модуля: ^tmp/otel/specification/ для spec, ^tmp/otlp/docs/ для otlp і ^tmp/semconv/docs/ для semconv.
  • context — Необовʼязково: body|front matter (зазвичай: body). Встановіть front matter для патчів, які змінюють front matter.
  • apply — Анонімна підпрограма, що містить підставлення регулярного виразу. Для патчів тіла вона працює з $_. Для патчів front matter вона працює з $frontMatterFromFile (через псевдонім $_).

Окремий крок реєстрації не потрібен — диспетчер applyPatches автоматично перебирає всі записи в @patches під час побудови.

2. Перевірка патчу

Виконайте крок копіювання специфікації та переконайтеся, що патч було застосовано:

npm run cp:spec

У разі успішного виконання помилок не буде. Потім ви можете пошукати проблемний вміст у вихідних даних tmp/, щоб переконатися, що його було переписано. Для патчів, повʼязаних із посиланнями, також виконайте:

npm run fix:refcache  # Prunes stale refcache entries, then checks links
npm test              # Full test run including link checking

3. Commit та push

Якщо ваш патч був створений під час виправлення PR refcache (наприклад, гілка otelbot/refcache-refresh), зафіксуйте зміни в adjust-pages.pl разом з оновленим refcache.json, а потім виконайте force-push з lease:

git add scripts/content-modules/adjust-pages.pl static/refcache.json
git commit -m "Patch adjust-pages.pl and refresh refcache"
git push --force-with-lease

4. Вилучення застарілих патчів

Як тільки новий випуск специфікації містить виправлення, cp:spec виводить повідомлення:

INFO: adjust-pages.pl: patch '<id>' is probably obsolete now that
spec '<name>' is at version '<new>' >= '<target>'; if so, remove the patch

Коли ви бачите це повідомлення, видаліть патч з масиву @patches. Якщо це останній патч, що залишився, ви можете закоментувати його замість видалення, щоб зберегти його як приклад для майбутніх патчів.

Востаннє змінено December 26, 2024: [uk] Ukrainian documentation for OpenTelemetry (cf1a5745)