非推奨警告が「狼少年」にならないようにする

PHPStanがメソッドを非推奨（deprecated）としてフラグ立てした場合、通常は代替手段を探します。しかし、もし代替手段が存在しなかったらどうでしょうか？

Shopwareでは、新しいオプション引数の追加といった計画的な変更を通知するために @deprecated タグを使用してきました。しかし、静的解析ツールはこれらのタグを「本当の非推奨」として扱い、すべての呼び出しに対して警告を出しました。その結果、ノイズが増大し、開発者は警告を無視するようになり、アラートの価値が失われてしまいました。これこそが、典型的な「狼少年（crying wolf）」の現象です。

Shopware 6.7.14.0 では、これらのシグナルを分離しました。

  • @deprecated – 消滅または置き換えられる予定のAPIのために予約してください。コードの移行が必須となります。
  • BC変更属性 – 新しいオプション引数の追加や戻り値の型の変更など、APIを維持したまま行う計画的な微調整に使用します。

新しい属性は Shopware\Core\Framework\Deprecation\BCChange に定義されています。これらは、何が変更されるのか、そして誰に影響するのかを正確に伝えます。

これらは2つのグループに分けられています。

  • CallSiteCompatibilityChange – メソッドを呼び出しているコードに影響します。
  • ExtenderCompatibilityChange – メソッドを継承またはオーバーライドしているクラスに影響します。

これにより、次のメジャーリリースが来る前に、拡張機能を Shopware 6.8 に向けて準備できるようになります。

例: あるメソッドに新しいオプション引数が追加される場合。今日その引数をオーバーライドに追加しておけば、現在のバージョンと将来のバージョンの両方でコードが動作します。

この変更により、非推奨警告に対する信頼が回復します。

開発者のための3つのステップ

  1. @deprecated は必須の修正として扱う。APIは消滅します。
  2. 本質的な問題を隠してしまうような、広範囲な ignore パターンを廃止する。
  3. BC変更属性を注視し、後で大規模な移行を行うのではなく、今、小さく安全なアップデートを適用する。

Source: https://dev.to/shopware/when-deprecated-cries-wolf-making-shopwares-next-major-upgrades-easier-983