@@ -119,7 +119,25 @@ an arbitrary value (ex: ``320``) will make the tests fails only if a higher
119119number of deprecation notices is reached (``0 `` is the default value). You can
120120also set the value ``"weak" `` which will make the bridge ignore any deprecation
121121notices. This is useful to projects that must use deprecated interfaces for
122- backward compatibility reasons.
122+ backward compatibility reasons, or for libraries that do not want deprecations
123+ triggered by their dependencies to prevent unrelated pull requests from being
124+ merged, which leads us to the ``"weak_vendors" `` value, described below.
125+
126+ When you maintain a library, having the test suite fail as soon as a dependency
127+ introduces a new deprecation is not desirable, because it shifts the burden of
128+ fixing that deprecation to any contributor that happens to submit a pull
129+ request shortly after a new vendor release is made with that deprecation. To
130+ mitigate this, you can either use tighter requirements, in the hope that
131+ dependencies will not introduce deprecations in a patch version, or even commit
132+ the Composer lock file, which would create another class of issues. Libraries
133+ will often use ``SYMFONY_DEPRECATIONS_HELPER=weak `` because of this. This has
134+ the drawback of allowing contributions that introduce deprecations but:
135+ * forget to fix the deprecated calls if there are any;
136+ * forget to mark appropriate tests with the ``@group legacy `` annotations.
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.
123141
124142Disabling the Deprecation Helper
125143~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~