Жизненный цикл изменений

Публичное имя Framework (атрибут, значение, событие, класс, токен, утилита, настройка, свойство, компонент) не исчезает без предупреждения. Каждое такое изменение записывается в журнал, какое-то время продолжает работать и удаляется в заранее известный день. Эта страница описывает, как это устроено; как применить изменения к своему проекту — в Как обновить проект.

Правила жизненного цикла записаны в contracts/lifecycle-policy.json и стандарте simai.change-lifecycle в репозитории ui-source.

Удаление по календарю

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

Два этапа

1. Совместимость (compat). Устаревшее имя работает через псевдоним. В журнале записано, какое имя писать вместо него и дата удаления устаревшего имени. Примеры документации показывают только каноническое имя; прежние имена компонента перечислены в таблице «Прежние имена» его страницы справочника. На работающей странице такое имя действует и отмечается в SF.deprecations, если компонент читает его через псевдоним; консоль по умолчанию молчит (см. Что устарело на работающей странице).
2. Удалено (removed). Кода устаревшего имени в поставке нет. Прежнее имя больше не читается и не отмечается в SF.deprecations. Запись в журнале остаётся навсегда: по ней можно обновить проект, закреплённый на любом более раннем выпуске.

Календарь

Чистка проходит 1-го числа каждого месяца.

• Имя удаляется в первую чистку, наступившую не менее чем через 30 дней после того, как оно устарело.
• Срок записи можно продлить один раз, не больше чем на 30 дней. Для продления нужна причина: какой продукт ещё зависит от имени и когда он перейдёт. Продлевают до наступления срока, а не после.
• За 7 дней до чистки проверки Framework выводят записи, срок которых подходит, как предупреждение, без падения.

Пример расчёта. Имя устарело 9 октября. Плюс 30 дней — 8 ноября. Ближайшее 1-е число начиная с этой даты — 1 декабря. Имя, устаревшее 30 сентября, удаляется 1 ноября.

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

Журнал изменений

Журнал изменений — машиночитаемый файл contracts/changes/journal.json в открытом репозитории simai/ui-source (формат simai.change-journal). В поставку ui журнал не входит; там же, в ui-source, лежит инструмент sf-upgrade (см. Инструмент sf-upgrade). Это единственный полный список изменений, которые требуют правки проекта. Записи только добавляются и никогда не удаляются.

Файл — один JSON-объект с тремя полями: имя формата, ссылка на правила жизненного цикла и список записей:

{
  "schema": "simai.change-journal",
  "schema_version": 1,
  "policy": "contracts/lifecycle-policy.json",
  "records": [
    {"id": "attribute-type-to-appearance", "stage": "compat", "…": "…"}
  ]
}

Скрипт, который читает журнал, берёт записи из поля records. Каждая запись отвечает на вопросы:

Пример записи (сокращено, в items оставлен один компонент):

{
  "id": "attribute-type-to-appearance",
  "stage": "compat",
  "kind": "attribute",
  "items": [{"component": "sf-button", "from": "type", "to": "appearance"}],
  "deprecated_on": "2026-10-09",
  "remove_after": "2026-12-01",
  "rewrite": "rename-attribute",
  "examples": {
    "before": "<sf-button type=\"outline\">",
    "after": "<sf-button appearance=\"outline\">"
  }
}

Что важно заметить: запись сама говорит, можно ли заменить имя механически (rewrite), до какого дня оно работает (remove_after) и как выглядит правильный код (examples). Как эту запись применяет инструмент — в Пример: запись журнала и её применение.

Содержание журнала в руководстве не перечисляется: оно меняется каждый месяц. Актуальный список — в самом файле журнала.

Что устарело на работающей странице

Smart-компоненты отмечают устаревшие атрибуты и значения, которые они читают через псевдоним. Список доступен прямо в браузере:

SF.deprecations.list();

Каждая строка — компонент, вид (атрибут или значение), устаревшее имя, каноническое имя и сколько раз оно встретилось. По умолчанию консоль молчит. Чтобы видеть предупреждения сразу, добавьте атрибут на корневой элемент:

<html data-sf-deprecations="warn">

или выполните SF.deprecations.warn = true.

Границы этого списка:

• объект SF.deprecations есть сразу после core.js, в том числе на странице без Smart-элементов; заполняется он, когда Smart-компоненты читают прежние имена;
• он показывает только то, что разбирают Smart-компоненты: атрибуты и их значения;
• в нём только имена, которые компонент читает через псевдоним. Часть прежних имён компонент разбирает своим кодом, и они не отмечаются даже с data-sf-deprecations="warn" (например, scheme со словом статуса у sf-badge). Какие прежние имена компонент отмечает, говорит столбец «Состояние» таблицы «Прежние имена» на его странице. Пустой список не доказывает, что прежних имён на странице нет; полную проверку даёт только sf-upgrade;
• устаревшие классы, утилиты, токены и имена событий в нём не видны — их находит только sf-upgrade по исходникам проекта (см. Инструмент sf-upgrade). Например, запись token-heading-font-unused выводит из ядра переменные --sf-heading--font-family, --sf-heading--font-weight и --sf-heading--font-style после 2026-12-01: их не читает ни одно правило. Гарнитуру и насыщенность заголовков (h1–h6, sf-h-1…sf-h-6) задают --sf-heading--family и --sf-heading--weight, крупных заголовков sf-display-* — --sf-display--family и --sf-display--weight, или свой класс на заголовке. Ручная работа по записи — перенести значения в эти переменные и убрать прежние из темы проекта (см. Все переменные).