From ed845bd6bbf670f4ff370ea3e7930d7def22564c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= Date: Thu, 16 Nov 2017 17:51:46 +0100 Subject: [PATCH 1/2] Document allow outdated vendors mode Refs https://github.com/symfony/symfony/pull/24867 --- components/phpunit_bridge.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index 892b1f1741d..97d14ca39e3 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -188,6 +188,16 @@ 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. +When working on a project, you might be more interested in the +``allow_outdated_vendors``, which is a bit more strict. Let's say you +want to fix deprecations as soon as they appear. A problem many people +experience is that some dependencies they have tend to lag behind their +own dependencies, meaning they do not fix deprecations as soon as +possible, which means there is nothing you can do to fix that (apart +from a pull request on the outdated vendor). This mode allows you to +ignore those deprecations, allowing you to notice when *your code* is +using deprecated APIs, and to keep up with the changes. + Disabling the Deprecation Helper ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From e7dee0c7b4d38824ff070565af67195f802a10ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= Date: Mon, 29 Jan 2018 20:02:04 +0100 Subject: [PATCH 2/2] Add a table to summarize the modes --- components/phpunit_bridge.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index 97d14ca39e3..88322af75b1 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -198,6 +198,29 @@ from a pull request on the outdated vendor). This mode allows you to ignore those deprecations, allowing you to notice when *your code* is using deprecated APIs, and to keep up with the changes. +Here is a summary that should help you pick the right mode: + ++------------------------+-----------------------------------------------------+ +| Mode | Recommended situation | ++========================+=====================================================+ +| strict | Recommended for actively maintained projects | +| | with little to no dependencies | ++------------------------+-----------------------------------------------------+ +| | Recommended for projects that you cannot | +| | immediately fix but don't want to make worse. | +| | Can be used to transition from one mode to another. | ++------------------------+-----------------------------------------------------+ +| allow_outdated_vendors | Recommended for projects with dependencies | +| | that fail to keep up with new deprecations. | ++------------------------+-----------------------------------------------------+ +| weak_vendors | Recommended for libraries that use | +| | the deprecation system themselves and | +| | cannot afford to use one of the modes above. | ++------------------------+-----------------------------------------------------+ +| weak | Not recommended; will probably lead to | +| | a big refactoring. | ++------------------------+-----------------------------------------------------+ + Disabling the Deprecation Helper ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~