@@ -121,6 +121,24 @@ also set the value ``"weak"`` which will make the bridge ignore any deprecation
121121notices. This is useful to projects that must use deprecated interfaces for
122122backward compatibility reasons.
123123
124+ When you maintain a library, having the test suite fail as soon as a dependency
125+ introduces a new deprecation is not desirable, because it shifts the burden of
126+ fixing that deprecation to any contributor that happens to submit a pull
127+ request shortly after a new vendor release is made with that deprecation. To
128+ mitigate this, you can either use tighter requirements, in the hope that
129+ dependencies will not introduce deprecations in a patch version, or even commit
130+ the Composer lock file, which would create another class of issues. Libraries
131+ will often use ``SYMFONY_DEPRECATIONS_HELPER=weak `` because of this. This has
132+ the drawback of allowing contributions that introduce deprecations but:
133+
134+ * forget to fix the deprecated calls if there are any;
135+ * forget to mark appropriate tests with the ``@group legacy `` annotations.
136+
137+ By using the ``"weak_vendors" `` value, deprecations that are triggered outside
138+ the ``vendors `` directory will make the test suite fail, while deprecations
139+ triggered from a library inside it will not, giving you the best of both
140+ worlds.
141+
124142Disabling the Deprecation Helper
125143~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126144