Управление и версионирование — Примеры

Пример 1 — Разбор запросов на дополняющие и ломающие

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

1  добавить variant="quiet" к Button; ничего существующего не меняется
2  переименовать свойство "tone" у Badge в "variant"
3  исправить рамку заголовка Card в состоянии ошибки

Решение

1  дополняющее   minor    выходит без проверки
2  ломающее      major    пронумеровать, написать миграцию, открыть окно устаревания
3  исправление   patch    корректная отрисовка документированного состояния

Владелец: команда системы. На ломающие изменения отвечают в течение пяти рабочих дней.

Новый вариант и исправление отрисовки могут выйти сразу: ничего из написанного потребителями не перестаёт работать. С переименованием так нельзя — каждое место вызова, которое передаёт tone, ломается при обновлении, поэтому ему нужны следующий мажорный номер, заметка о миграции и окно, в котором работают оба написания. Обычный провал — выпустить переименование как minor, потому что в диффе оно маленькое; критерий здесь не размер, а ломается ли существующий вызов.

Пример 2 — Устаревание с датой, а не с пожеланием

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

Решение
  токен grey-200 становится surface-muted
  потребители: шесть экранов
  владелец: команда системы
  удаление: конец текущего квартала

Решение

Устарело     grey-200
Заменено на  surface-muted
Удаление     конец текущего квартала; тогда старый токен перестаёт разрешаться
Миграция     замените var(--grey-200) на var(--surface-muted)
             оба имени разрешаются до даты удаления

Потребители обязаны мигрировать до даты удаления. Миграция
указана задачей у каждой команды-потребителя, а не пожеланием.

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