Обратная совместимость
В разделе изложены общие правила обеспечения обратной совместимости, применяемые в SDK пользовательского интерфейса. Эти правила задают прозрачный и предсказуемый подход: с одной стороны они позволяют продуктовой команде развивать SDK, а с другой — обеспечивают потребителям безопасную миграцию на новые версии и возможность своевременно планировать работы.
Термины
- Гарантия обратной совместимости — наличие в новой версии SDK продукта API, присутствующего в старой версии, в результате чего, потребители могут продолжать работать с новой версией SDK продукта без изменений.
- Элемент API — минимальная часть публичного интерфейса SDK (как исполняемая, так и декларативная), доступная для использования внешними потребителями.
Жизненный цикл элементов API
Каждому элементу API присвоен определённый статус, который определяет срок его жизненного цикла и уровень гарантий совместимости:
| Статус | TSDoc-тэги | Гарантия обратной совместимости | Для внешних потребителей | Описание |
|---|---|---|---|---|
| @public | Да | Да | Стабильный элемент API, который не планируется к изменениям. Рекомендован к использованию | |
| @public @deprecated | Да (минимальный срок поддержки) | Да | Стабильный элемент API, который устарел и в дальнейшем будет удалён. Не рекомендован к использованию | |
| @beta | Нет | Да | Нестабильный элемент API, который может меняться. Рекомендован к использованию, если нет требований к стабильности | |
| @internal | Нет | Нет | Внутренний элемент API, к которому по техническим причинам существует доступ. Не рекомендован к использованию |
Статус элемента API задаётся в декларации типов SDK API в виде TSDoc-тэгов, а также указывается в документации.
Статус может меняться только с выходом новой мажорной версии продукта и строго определенным образом:
| Текущий статус | Следующий статус |
|---|---|
или или Удалённый |
|
или Удалённый |
Об изменении статуса сообщается в разделе Журнал изменений. Если элемент API помечается как устаревший, то информация об этом так же попадает в раздел Устаревшее API.
Исключением является Внутренний элемент API, он может быть изменен/удалён без предупреждения и без уведомления в любой новой версии продукта.
Гарантия обратной совместимости
Обратная совместимость обеспечивается только для Стабильных элементов API. Для некоторых стабильных элементов API могут присутствовать ограничения по гарантиям, о чём явно указывается в документации к этой функциональности.
Для устаревших элементов API обратная совместимость гарантируется только на минимальный срок поддержки.
Минимальный срок поддержки устаревшего API
Срок поддержки Устаревшего элемента API составляет 6 месяцев, начиная с даты выхода версии продукта в которой этот элемент API был объявлен устаревшим, до даты выхода версии в которой элемент API может быть удален/изменен. Все промежуточные версии (если таковые имеются) сохраняют работоспособность Устаревшего API.
Пример:
Имеется класс Obj с тремя методами foo, baz и quz. В течении жизненного цикла первые два метода (foo и bar)
объявляются устаревшими в пользу методов bar и qux соответственно, а третий (quz) удаляется без альтернативы
для миграции. На временном графике показано, как будет выглядеть жизненный цикл этих элементов API, согласно текущим
правилам:
Нарушение обратной совместимости
Нарушение обратной совместимости API SDK допускается только в мажорных версиях продукта и только в следующих случаях:
-
Функциональность, которую поддерживал элемент API, была значительно изменена или полностью удалена из продукта.
Пример:
Ранее в продукте присутствовала страница, для которой в SDK были реализованы точки расширения. В последующей версии продукта эта страница была полностью удалена. Соответственно, и точки расширения, расширяющие функциональность этой страницы так же полностью удаляются, так как теряют смысл.
-
Элементу API ранее был установлен статус "Устаревший" и он просуществовал в этом статусе минимальный срок поддержки
Любые изменения о нарушении обратной совместимости фиксируются в разделе Журнал изменений.