Document the weak_vendors value

Author: greg0ire

components/phpunit_bridge.rst

@@ -119,7 +119,25 @@ an arbitrary value (ex: ``320``) will make the tests fails only if a higher
 number of deprecation notices is reached (``0`` is the default value). You can
 also set the value ``"weak"`` which will make the bridge ignore any deprecation
 notices. This is useful to projects that must use deprecated interfaces for
-backward compatibility reasons.
+backward compatibility reasons, or for libraries with lots of vendors that
+can create a sudden backlog of deprecations to fix that would otherwise prevent
+unrelated pull requests from being merged… which leads us to ``"weak_vendors"``.
+
+When you maintain a library with a lot of vendors, having the test suite fail
+as soon as a dependency introduces a new deprecation is not desirable, because
+it shifts the burden of fixing that deprecation to any contributor that happens
+to submit a pull request shortly after a new vendor release is made with that
+deprecation. To mitigate this, you can either use tighter requirements, in the
+hope that dependencies will not introduce deprecations in a patch version, or
+even commit the Composer lock file, which would create another class of issues.
+Libraries will often use ``SYMFONY_DEPRECATIONS_HELPER=weak`` because of this.
+This has the drawback of allowing contributions that introduce deprecations but:
+* forget to fix the deprecated calls if there are any;
+* forget to mark appropriate tests with the ``@group legacy`` annotations.
+By using the ``"weak_vendors"`` value, deprecations that are triggered outside
+the ``vendors`` directory will make the test suite fail, while deprecations
+triggered from a library inside it will not, giving you the best of both
+worlds.
 
 Disabling the Deprecation Helper
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~