Миграция
Переезды между мажорами: что сломал переход с 0.x на 1.0 и как его пройти.
Мажорный переход у библиотеки один — с 0.x на 1.0. Публичная поверхность — компоненты, их подпути, токены и реестры — осталась той же, что в 0.53. Сменился конвейер, которым приложение собирает CSS. Поэтому переезд ломающий, хотя ни один импорт компонента не меняется.
С 0.x на 1.0
| Было в 0.x | Стало в 1.0 |
|---|---|
peer @feugene/unocss-preset-granular | peer @feugene/granum >=1.0.0 <2.0.0 и движок @feugene/granum-engine-wind |
uno.config.ts | granum.config.ts; движок передаётся инстансом — engine: windEngine() |
| CSS склеивался по порядку подключения | CSS приезжает модулем virtual:granum.css пятью слоями granum.* |
| сброс браузерных стилей — обычным CSS | сброс — в слое: @import '…' layer(reset);, иначе он перебьёт библиотеку |
defineGranularComponent, defineGranularProvider | defineGranumComponent, defineGranumProvider из @feugene/granum/contract — для авторов провайдеров |
Спутники, которые зависят от ядра, перешли на 1.0 в тот же день: их диапазон
ядра теперь >=1.0.0 <2.0.0, и с ядром 0.x он не сходится. Поэтому ядро и
спутники обновляются вместе. Пошаговое руководство — в документации granum
(ru,
en).
Ломающие правки внутри линии 0.x — в журнале изменений.
Что появится здесь к следующему мажору
- Карта изменений API — что переименовано, что удалено, что поменяло значение по умолчанию. Таблицей, а не прозой: по прозе не сделать поиск по имени пропа.
- Codemod. Переименования выполняются скриптом, а не руками: он живёт в репозитории рядом с миграцией и запускается одной командой.
- Что ломается молча. Отдельный раздел под изменения, которые не дают ни ошибки сборки, ни предупреждения, — сдвиг значения по умолчанию, смена порядка разрешения, другой ARIA-контракт. Это самая дорогая часть переезда и самая короткая в чужих гайдах. Один такой случай известен уже по 1.0 — сброс вне слоя, см. типовые поломки.
- Порядок действий для приложения, которое обновляется не сразу: что можно ставить рядом, что конфликтует, где проходит граница совместимости.
- Оценка трудоёмкости по размеру приложения — чтобы решение «переезжать сейчас или в следующем квартале» принималось по числу, а не по настроению.
Версии документации
Документация одна и описывает линию 1.x; архива 0.x на портале нет. Версия в шапке читается из манифеста установленного ядра на сборке и руками не пишется — она совпадает с тем, на чём собран портал.
Подробности политики версий — на странице версионирования.
Переход с другой библиотеки — это не миграция в этом смысле. Карты соответствия компонентов для него готовятся на отдельной странице — «Переход с другой библиотеки».