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

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

---

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

---

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

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

## Що робить скрипт {#what-the-script-does}

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

- **Додавання 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` та оновлюються автоматично відповідним робочим процесом.

## Патчі специфікацій між випусками {#patching-specs}

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

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

### 1. Додавання патчу {#1-add-a-patch-entry}

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

```perl
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. Перевірка патчу {#2-test-the-patch}

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

```sh
npm run cp:spec
```

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

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

### 3. Commit та push {#3-commit-and-push}

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

```sh
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. Вилучення застарілих патчів {#4-remove-obsolete-patches}

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

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

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

[content-modules]: https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules
[cp-pages]: https://github.com/open-telemetry/opentelemetry.io/blob/main/scripts/content-modules/cp-pages.sh
[script]: https://github.com/open-telemetry/opentelemetry.io/blob/main/scripts/content-modules/adjust-pages.pl