Версии библиотеки компонентов: semver и ломающие изменения

Прямой ответ

Версия библиотеки компонентов изменяется по характеру изменения: удаление либо переименование свойства требует новой основной версии, добавление — дополнительной.

{ "dependencies": { "@acme/ui": "^2.1.0" } }

Удаление свойства нарушает работу потребителя, поэтому изменение выпускается новой основной версией. О правиле нумерации — в статье про semver.

Что считается ломающим изменением

Ломающее изменение нарушает работу потребителя без правки его кода, поэтому характер изменения определяет часть версии.

Удаление либо переименование свойства. Потребитель передаёт свойство, которое больше не принимается, поэтому поведение изменяется без правки кода потребителя.

Изменение значения по умолчанию. Поведение без передачи свойства изменяется, поэтому потребитель, не передававший свойство, получает другой результат.

Изменение структуры разметки. Стиль потребителя, нацеленный на прежнюю структуру, перестаёт применяться, поэтому оформление нарушается.

Практическое следствие: выпуск изменения значения по умолчанию в дополнительной версии приводит к смене поведения у потребителей, обновившихся без правки кода.

Отдельный аспект — изменение визуального оформления. Обновление значения токена меняет внешний вид без изменения интерфейса компонента, поэтому характер изменения определяется тем, нарушается ли работа потребителя, а не тем, видно ли изменение.

Диапазоны версий и обновление потребителя

Диапазон версий определяет, какие версии устанавливаются при обновлении, поэтому потребитель контролирует переход через основную версию.

Диапазон в пределах основной версии. Дополнительная версия и номер сборки устанавливаются автоматически, поэтому добавление свойства применяется без правки кода.

Переход через основную версию. Выполняется явно потребителем, поэтому ломающее изменение не применяется без решения о переходе.

Фиксация версии. Точная версия фиксирует состояние, поэтому обновление выполняется по решению, а не при установке.

Практическое следствие: диапазон, включающий основную версию, приводит к установке ломающего изменения при обновлении, поэтому работа потребителя нарушается без явного перехода.

Описание изменений и план перехода

Описание изменений перечисляет, что изменилось в версии, поэтому потребитель определяет объём правки до обновления.

Перечень изменений. Каждое изменение версии описывается, поэтому поиск изменения по коду не требуется.

Отметка ломающего изменения. Изменение, нарушающее работу потребителя, отмечается явно, поэтому объём правки известен до обновления.

План перехода. Последовательность действий для перехода описывается, поэтому обновление выполняется по шагам, а не подбором.

Практическое следствие: описание без отметки ломающего изменения требует проверки поведения после обновления, поэтому нарушение обнаруживается в работе, а не до перехода.

О составе пакета — в статье про публикацию библиотеки; о структуре системы — в статью про дизайн‑систему.

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

Описание версий обновляется при каждом выпуске, поэтому потребитель определяет объём правки до обновления.

Новое свойство. Добавление свойства описывается в дополнительной версии, поэтому потребитель знает о новой возможности.

Ломающее изменение. Отмечается в описании основной версии, поэтому объём правки известен до перехода.

Исправление без изменения интерфейса. Описывается в номере сборки, поэтому потребитель отличает исправление от изменения поведения.

Практическое следствие: выпуск без описания требует проверки поведения после обновления, поэтому нарушение обнаруживается в работе приложения, а не до перехода на новую версию.

Практика: выпуск версий библиотеки

1. Определяйте характер изменения до выпуска. Часть версии определяется тем, нарушается ли работа потребителя.

2. Выпускайте удаление свойства основной версией. Потребитель переходит явно, а не при обновлении.

3. Отмечайте изменение значения по умолчанию как ломающее. Поведение без передачи свойства изменяется.

4. Описывайте каждое изменение версии. Поиск изменения по коду не требуется.

5. Отмечайте ломающие изменения явно. Объём правки известен до обновления.

6. Описывайте план перехода для основной версии. Обновление выполняется по шагам.

7. Не допускайте основную версию в диапазон автоматического обновления. Ломающее изменение не устанавливается без решения.

Рекомендации:

1. Не выпускайте изменение значения по умолчанию дополнительной версией. Поведение потребителей меняется без правки кода.
2. Не считайте визуальное изменение автоматически ломающим. Характер определяется нарушением работы потребителя.
3. Фиксируйте версию в приложениях с критичным оформлением. Обновление выполняется по решению, а не при установке.
4. Сопровождайте основную версию планом перехода. Обновление по шагам сокращает число ошибок при переходе.
5. Пересматриваем состав описания при каждом выпуске. Изменение без описания требует проверки поведения после обновления.

Практический сценарий: обновление библиотеки сломало оформление

Контекст: после обновления библиотеки компонентов часть кнопок потеряла оформление, при этом код приложения не изменялся.

1. Диагностика. Сравнение версий показало, что обновление затронуло дополнительную версию, но компонент изменил структуру разметки. Стиль приложения был нацелен на прежнюю структуру, поэтому после обновления правило перестало применяться.
2. Причина. Изменение структуры разметки было выпущено дополнительной версией, хотя нарушало работу потребителя. Диапазон версий в приложении включал дополнительные версии, поэтому обновление установилось автоматически.
3. Действия. (а) Выпустили исправление, вернувшее прежнюю структуру, и описали изменение как ломающее в описании версии; (б) зафиксировали версию библиотеки в приложении, чтобы обновление выполнялось по решению; (в) установили правило, по которому изменение структуры разметки выпускается основной версией; (г) добавили отметку ломающего изменения в описание каждой версии, чтобы объём правки был известен до обновления; (д) описали план перехода для основной версии, чтобы потребитель выполнял обновление по шагам.
4. Результат. Обновление библиотеки не применяется автоматически при изменении, нарушающем работу потребителя, поэтому переход выполняется по плану.

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

FAQ

Что считается ломающим изменением в библиотеке компонентов? Удаление либо переименование свойства, изменение значения по умолчанию и изменение структуры разметки. Работа потребителя нарушается без правки кода.

Как выпускать изменение значения по умолчанию? Основной версией. Потребитель, не передававший свойство, получает другой результат.

Почему не допускать основную версию в диапазон обновления? Ломающее изменение установится автоматически, поэтому работа потребителя нарушится без явного решения о переходе.

Что содержать в описании версии? Перечень изменений, отметку ломающих изменений и план перехода для основной версии.

Источники: Semantic Versioning, npm package.json, Keep a Changelog — ссылки в шапке.