Changelog и breaking changes

Понимание Changelog

Changelog — это документ, фиксирующий все изменения между версиями библиотеки. В случае Lighthouse Changelog структурирован для удобного отслеживания новых возможностей, исправлений ошибок и изменений, которые могут нарушить обратную совместимость. Каждый выпуск содержит:

  • Номер версии — следует стандарту семантического версионирования (semver), например 10.2.0.
  • Дата релиза — позволяет понять, когда изменения были официально опубликованы.
  • Тип изменения — новые функции (Features), исправления (Fixes), изменения, влияющие на совместимость (Breaking Changes).

Пример структуры записи:

## [10.2.0] - 2026-02-01
### Added
- Новые аудиты производительности для веб-шрифтов
### Fixed
- Ошибка в модуле анализа изображений
### Breaking Changes
- Метод `lighthouse.runner.run()` больше не принимает объект настроек `legacySettings`

Breaking changes: основные принципы

Breaking change — изменение, которое нарушает работу кода, написанного для предыдущих версий. В Lighthouse такие изменения встречаются регулярно из-за постоянного обновления стандартов веб-производительности и аудитории браузеров. Основные типы:

  1. Удаление устаревших API

    • Старые методы, объекты или параметры, объявленные deprecated в предыдущих версиях, полностью убираются.
    • Пример: раньше можно было запускать Lighthouse с flags.chromePath, теперь путь к Chrome задаётся через новый объект launchOptions.

  2. Изменение структуры данных

    • Результаты аудитов или отчётов могут изменять формат JSON.
    • Пример: ключ timing в performanceMetrics может быть разбит на отдельные метрики с более точными измерениями (firstContentfulPaint, largestContentfulPaint).

  3. Обновление зависимостей

    • Если Lighthouse обновляет внутренние пакеты (например, Chrome Launcher, Puppeteer), это может требовать изменения конфигурации проекта.
    • Пример: новая версия Puppeteer использует другой метод запуска headless-браузера, что влияет на скрипты интеграции.

Отслеживание изменений через Changelog

  • Каждое изменение сопровождается кратким описанием и ссылкой на Pull Request или Issue.
  • Breaking changes всегда выделены отдельным разделом и снабжены рекомендациями по миграции.
  • Для версий с повышением major number (9.x → 10.0) следует ожидать наибольшее количество изменений, нарушающих совместимость.

Практические рекомендации при работе с breaking changes

  1. Внимательное чтение Changelog перед обновлением

    • Определить, какие функции используются в текущем проекте.
    • Сравнить их с разделом Breaking Changes.

  2. Использование feature flags или условной поддержки

    • Для устаревших API можно временно оставлять поддержку через полифилы или адаптеры.

  3. Автоматизированные тесты

    • Поддержание набора unit и integration тестов позволяет быстро выявить поломки после обновления.

  4. Версионирование зависимостей

    • Фиксировать версии в package.json через ^ или ~ аккуратно, чтобы избегать автоматического скачивания major-обновлений без проверки Changelog.

Инструменты для анализа Breaking Changes в Lighthouse

  • Локальные скрипты для diff JSON Позволяют сравнивать отчёты старой и новой версии Lighthouse и выявлять изменения структуры.

  • CI/CD интеграции Автоматическое выполнение Lighthouse на всех ветках проекта с последующей проверкой на ошибки или отклонения в метриках.

  • Линтеры конфигурации Проверяют корректность новых параметров и предупреждают использование устаревших.

Примеры реальных breaking changes

  1. Изменение формата аудита Accessibility

    • Старый результат: audits.accessibility.score — число от 0 до 100.
    • Новый формат: audits.accessibility.details.items — массив объектов, описывающих каждый найденный дефект.

  2. Удаление --output=json в CLI

    • Теперь вывод JSON требует явного указания через --output=json,html.

  3. Смена ключевых зависимостей

    • Chrome Launcher обновился с версии 0.14 до 1.0, изменился API запуска браузера. Старые вызовы с chromeFlags перестают работать.

Эти изменения требуют пересмотра кода, обновления скриптов автоматизации и корректировки интеграционных тестов.

Подводя ключевые моменты

  • Changelog — источник достоверной информации о всех изменениях.
  • Breaking changes требуют особого внимания: они могут сломать существующую инфраструктуру.
  • Применение версионирования и тестирования снижает риск поломки при обновлении.

Использование детального анализа Changelog и внимательное отслеживание breaking changes позволяет безопасно интегрировать новые версии Lighthouse, не нарушая стабильность текущих проектов.

Оглавление