Changelog и breaking changes

Shepherd.js — это современная библиотека для создания интерактивных пошаговых туров по веб-приложениям. Правильное отслеживание изменений в версии библиотеки и понимание breaking changes критически важно для поддержки существующего кода и миграции на новые версии.

Основные принципы Changelog

Changelog в Shepherd.js структурирован таким образом, чтобы различать три типа изменений:

  1. Added — новые функции и возможности.
  2. Changed — модификации существующего функционала, которые не нарушают совместимость.
  3. Deprecated — устаревшие методы и свойства, которые будут удалены в будущих версиях.
  4. Removed — полностью удалённые возможности.
  5. Fixed — исправления багов.
  6. Breaking Changes — изменения, требующие внесения правок в существующий код.

Каждая версия библиотеки сопровождается подробным описанием изменений. Формат часто включает номер версии, дату выпуска и список изменений, сгруппированных по вышеуказанным категориям.

Структура Breaking Changes

Breaking changes (или несовместимые изменения) в Shepherd.js обычно затрагивают следующие области:

  • API шагов (Step API) Методы addStep, removeStep, getCurrentStep могут изменять сигнатуру или поведение. Например, в версии 8.x был изменён формат конфигурации шага: buttons теперь должны быть массивом объектов с обязательным полем text, а не строкой.

    // Старый синтаксис
tour.addStep('intro', {
  text: 'Добро пожаловать',
  buttons: ['Далее']
});

// Новый синтаксис
tour.addStep('intro', {
  text: 'Добро пожаловать',
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

  • Обработчики событий (Event Handlers) Некоторые события были переименованы или изменили поведение. Например, show и hide шагов в версиях выше 8.x теперь возвращают промис, что требует асинхронного использования:

    await step.show();
await step.hide();

  • Настройки навигации и ориентации Конфигурация attachTo (элемент и позиция) в новых версиях стала более строгой. Ранее можно было передавать только селектор, теперь необходимо указывать объект:

    // Старый способ
attachTo: '.button'

// Новый способ
attachTo: {
  element: '.button',
  on: 'bottom'
}

  • Модули и экспорт библиотеки Shepherd.js перешёл на ESM-модули, что влияет на способ импорта:

    // Старый способ
const Shepherd = require('shepherd.js');

// Новый способ
import Shepherd from 'shepherd.js';

Советы по безопасной миграции

  1. Внимательное изучение Changelog каждой версии Необходимо проверять изменения между текущей версией и целевой, особенно раздел Breaking Changes. Мелкие изменения в конфигурации могут вызвать полное падение туров.

  2. Использование опции defaultStepOptions Для минимизации необходимости правок на каждом шаге рекомендуется задавать общие параметры через defaultStepOptions. Это позволяет централизованно обновлять настройки.

    const tour = new Shepherd.Tour({
  defaultStepOptions: {
    cancelIcon: {
      enabled: true
    },
    scrollTo: { beh * avior: 'smooth', block: 'center' }
  }
});

  3. Тестирование на каждой промежуточной версии При обновлении сразу на несколько мажорных версий возможны накопленные breaking changes. Лучше обновлять поэтапно и проверять функционал шагов и кнопок.

  4. Проверка асинхронных методов Все шаги, события и действия, возвращающие промис, должны использовать await или .then(). Игнорирование этого требования может привести к некорректному отображению шагов.

  5. Обновление кастомных CSS и классов В некоторых версиях изменяются внутренние классы шагов (shepherd-step, shepherd-button), что может нарушить кастомные стили. Следует проверять визуальное оформление после обновления.

Примеры типичных breaking changes

  • Удаление старых методов: tour.nextStep() был заменён на tour.next().
  • Изменение структуры кнопок: обязательное наличие action и text.
  • Переход на промисы для событий: step.show() теперь асинхронный.
  • Строгая типизация attachTo: необходимо указывать объект с element и on.
  • Смена импорта на ESM: нельзя использовать require без трансформации сборки.

Поддержка устаревших версий

Shepherd.js сохраняет поддержку предыдущих версий в течение ограниченного времени, но для долгосрочного проекта рекомендуется миграция на актуальные версии, так как баги и уязвимости исправляются только в новых релизах.

Для больших проектов полезно вести собственный внутренний Changelog, фиксируя:

  • Какие шаги требуют изменения конфигурации.
  • Какие кастомные обработчики событий нужно адаптировать.
  • Какие CSS классы были изменены.

Это позволяет минимизировать риски при обновлении библиотеки.

Оглавление