Миграция
Переезды между мажорами. Страница создана заранее и пуста намеренно: у линии 0.x мажоров ещё не было.
Мигрировать пока не с чего. Ядро живёт в линии 0.x, мажорных переходов не
было, и эта страница существует раньше своего содержания намеренно: план
разделов, написанный заранее, стоит вечер, а написанный в день релиза — неделю и
нервы тех, кто переезжает.
Что делать сегодня, если версия обновилась и что-то отвалилось: смотреть журнал изменений — до 1.0 ломающие правки живут там, с описанием и датой.
Что здесь появится к 1.0
- Карта изменений API — что переименовано, что удалено, что поменяло значение по умолчанию. Таблицей, а не прозой: по прозе не сделать поиск по имени пропа.
- Codemod. Переименования выполняются скриптом, а не руками: он живёт в репозитории рядом с миграцией и запускается одной командой.
- Что ломается молча. Отдельный раздел под изменения, которые не дают ни ошибки сборки, ни предупреждения, — сдвиг значения по умолчанию, смена порядка разрешения, другой ARIA-контракт. Это самая дорогая часть переезда и самая короткая в чужих гайдах.
- Порядок действий для приложения, которое обновляется не сразу: что можно ставить рядом, что конфликтует, где проходит граница совместимости.
- Оценка трудоёмкости по размеру приложения — чтобы решение «переезжать сейчас или в следующем квартале» принималось по числу, а не по настроению.
Как будет устроено версионирование
Пока мажор один, документация одна и живёт по адресам без префикса. С выходом
1.0 текущее дерево копируется в архив /v0/, получает баннер и канонические
ссылки на актуальные аналоги, а переключатель версий появляется в шапке
документации рядом с версией пакета.
Версия в шапке читается из манифеста ядра на сборке — руками она не пишется, и поэтому не расходится с тем, что стоит в npm.
Подробности политики поддержки версий — на странице версионирования.
Переход с другой библиотеки — это не миграция в этом смысле, и живёт она отдельно: «Переход с другой библиотеки».