Как сделать так, чтобы предупреждения об устаревании не превращались в «ложную тревогу»

Когда PHPStan помечает метод как устаревший (deprecated), вы обычно ищете ему замену. Но что делать, если замены не существует?

Shopware использовала тег @deprecated для анонса планируемых изменений — например, добавления нового необязательного параметра. Инструменты статического анализа воспринимали эти теги как реальное устаревание и выдавали ошибки при каждом вызове. Шум нарастал, разработчики начали игнорировать предупреждения, и оповещения потеряли свою ценность. Это классический случай «ложной тревоги».

В Shopware 6.7.14.0 мы разделили эти сигналы.

  • @deprecated — зарезервируйте этот тег для API, которые исчезнут или будут заменены. Вам необходимо будет мигрировать свой код.
  • Атрибуты BC-change — используйте их для запланированных правок, которые сохраняют работоспособность API, таких как новые необязательные параметры или измененные типы возвращаемых значений.

Новые атрибуты находятся в Shopware\Core\Framework\Deprecation\BCChange. Они точно говорят вам, что именно изменится и кого это затронет.

Мы разделили их на две группы:

  • CallSiteCompatibilityChange — влияет на код, который вызывает метод.
  • ExtenderCompatibilityChange — влияет на классы, которые расширяют или переопределяют метод.

Теперь вы можете подготовить свое расширение к Shopware 6.8 еще до выхода следующего мажорного релиза.

Пример: метод получит новый необязательный параметр. Добавьте этот параметр в свои переопределения уже сегодня; тогда код будет работать как в текущей, так и в будущих версиях.

Это изменение возвращает доверие к предупреждениям об устаревании.

Три шага для разработчиков

  1. Относитесь к @deprecated как к обязательному исправлению; API исчезнет.
  2. Откажитесь от широких паттернов игнорирования, которые могут скрывать реальные проблемы.
  3. Следите за атрибутами BC-change и вносите небольшие безопасные обновления сейчас, чтобы избежать масштабной миграции в будущем.

Источник: https://dev.to/shopware/when-deprecated-cries-wolf-making-shopwares-next-major-upgrades-easier-983