From 884c0637533b7e6e307a6196017373764708eeee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= Date: Sat, 24 Nov 2018 15:15:06 +0100 Subject: [PATCH 1/5] Document changes in the deprecation error handler See https://github.com/symfony/symfony/pull/29211 See https://github.com/symfony/symfony/issues/28048 --- bundles/best_practices.rst | 4 +- components/phpunit_bridge.rst | 110 +++++++++++++++++++++++++--------- setup/bundles.rst | 2 +- setup/upgrade_major.rst | 10 ++-- 4 files changed, 90 insertions(+), 36 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 2091016cecf..0ff2416e37e 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -197,9 +197,9 @@ of Symfony and the latest beta release: include: # Minimum supported dependencies with the latest and oldest PHP version - php: 7.2 - env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors" + env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[internal]=0" - php: 7.0 - env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors" + env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[internal]=0" # Test the latest stable release - php: 7.0 diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index dec8e1cf10a..143a6cfac1e 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -28,7 +28,7 @@ Installation .. code-block:: terminal - $ composer require --dev "symfony/phpunit-bridge:*" + $ composer require --dev symfony/phpunit-bridge .. include:: /components/require_autoload.rst.inc @@ -178,7 +178,7 @@ message, enclosed with ``/``. For example, with: - + @@ -188,39 +188,89 @@ message contains the ``"foobar"`` string. Making Tests Fail ~~~~~~~~~~~~~~~~~ -By default, any non-legacy-tagged or any non-`@-silenced`_ deprecation notices -will make tests fail. Alternatively, setting ``SYMFONY_DEPRECATIONS_HELPER`` to -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. - -When you maintain a library, 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: +By default, any non-legacy-tagged or any non-`@-silenced`_ deprecation +notices will make tests fail. Alternatively, you can configure an +arbitrary threshold by setting ``SYMFONY_DEPRECATIONS_HELPER`` to +``max[total]=320`` for instance. It will make the tests fails only if a +higher number of deprecation notices is reached (``0`` is the default +value). + +You can even finer-grained control by using other keys of the ``max`` +array, which are ``internal``, ``direct``, and ``indirect``. The +``SYMFONY_DEPRECATIONS_HELPER`` environment variable accept a +url-encoded string, meaning you can combine thresholds and any other +configuration setting, like this: +``SYMFONY_DEPRECATIONS_HELPER=max[total]=42&max[internal]=0&verbose=0`` + +Internal deprecations +..................... + +When you maintain a library, 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=max[total]=999999`` 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. +By using ``SYMFONY_DEPRECATIONS_HELPER=max[internal]=0``, +deprecations that are triggered outside the ``vendors`` directory will +be accounted for seperately, while deprecations triggered from a library +inside it will not (unless you reach 999999 of these), giving you +the best of both worlds. + +Direct and indirect deprecations +................................ + +When working on a project, you might be more interested in +``max[direct]``. 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 those (apart from a pull request on the outdated vendor). +This key allows you to put a threshold on direct deprecations only, +allowing you to notice when *your code* is using deprecated APIs, and to +keep up with the changes. You can of course still use ``max[indirect]`` +if you want to keep indirect deprecations under a given threshold. + +Here is a summary that should help you pick the right configuration: + ++------------------------+-----------------------------------------------------+ +| Value | Recommended situation | ++========================+=====================================================+ +| max[total]=0 | Recommended for actively maintained projects | +| | with little to no dependencies | ++------------------------+-----------------------------------------------------+ +| max[direct]=0 | Recommended for projects with dependencies | +| | that fail to keep up with new deprecations. | ++------------------------+-----------------------------------------------------+ +| max[internal]=0 | Recommended for libraries that use | +| | the deprecation system themselves and | +| | cannot afford to use one of the modes above. | ++------------------------+-----------------------------------------------------+ + +Disabling the verbose output +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the brige will display a detailed output with the number of +deprecations and where they arise. If this is too much for you, you can +use ``SYMFONY_DEPRECATIONS_HELPER=verbose=0`` to turn the verbose output +off. Disabling the Deprecation Helper ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Set the ``SYMFONY_DEPRECATIONS_HELPER`` environment variable to ``disabled`` to -completely disable the deprecation helper. This is useful to make use of the -rest of features provided by this component without getting errors or messages -related to deprecations. +Set the ``SYMFONY_DEPRECATIONS_HELPER`` environment variable to +``disabled=1`` to completely disable the deprecation helper. This is +useful to make use of the rest of features provided by this component +without getting errors or messages related to deprecations. .. _write-assertions-about-deprecations: @@ -246,6 +296,10 @@ class autoloading time. This can be disabled with the ``debug-class-loader`` opt +.. versionadded:: 4.2 + + The ``DebugClassLoader`` integration was introduced in Symfony 4.2. + Write Assertions about Deprecations ----------------------------------- @@ -284,7 +338,7 @@ Running the following command will display the full stack trace: .. code-block:: terminal - $ SYMFONY_DEPRECATIONS_HELPER='/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit + $ SYMFONY_DEPRECATIONS_HELPER='regex=/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit Time-sensitive Tests -------------------- diff --git a/setup/bundles.rst b/setup/bundles.rst index a83916898c7..53104c6c9ba 100644 --- a/setup/bundles.rst +++ b/setup/bundles.rst @@ -142,7 +142,7 @@ following recommended configuration as the starting point of your own configurat matrix: include: - php: 5.3.3 - env: COMPOSER_FLAGS='--prefer-lowest --prefer-stable' SYMFONY_DEPRECATIONS_HELPER=weak + env: COMPOSER_FLAGS='--prefer-lowest --prefer-stable' SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 - php: 5.6 env: SYMFONY_VERSION='2.7.*' - php: 5.6 diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst index b8c00234fc8..16fb2a5f9c7 100644 --- a/setup/upgrade_major.rst +++ b/setup/upgrade_major.rst @@ -97,9 +97,9 @@ done! Sometimes, you can't fix all deprecations (e.g. something was deprecated in 3.4 and you still need to support 3.3). In these cases, you can still - use the bridge to fix as many deprecations as possible and then switch - to the weak test mode to make your tests pass again. You can do this by - using the ``SYMFONY_DEPRECATIONS_HELPER`` env variable: + use the bridge to fix as many deprecations as possible and then allow + more of them to make your tests pass again. You can do this by using the + ``SYMFONY_DEPRECATIONS_HELPER`` env variable: .. code-block:: xml @@ -108,11 +108,11 @@ done! - + - (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=weak phpunit``). + (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 phpunit``). .. _upgrade-major-symfony-composer: From 14fe935d5794b36e66fa63f28da2c068c055c817 Mon Sep 17 00:00:00 2001 From: Olena Kirichok Date: Sun, 28 Apr 2019 17:40:55 +0200 Subject: [PATCH 2/5] fixup! Document changes in the deprecation error handler --- bundles/best_practices.rst | 4 ++-- components/phpunit_bridge.rst | 27 ++++++++++++++------------- 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 0ff2416e37e..0423f2f1a02 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -197,9 +197,9 @@ of Symfony and the latest beta release: include: # Minimum supported dependencies with the latest and oldest PHP version - php: 7.2 - env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[internal]=0" + env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[self]=0" - php: 7.0 - env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[internal]=0" + env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[self]=0" # Test the latest stable release - php: 7.0 diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index 143a6cfac1e..ae4764e8297 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -195,12 +195,12 @@ arbitrary threshold by setting ``SYMFONY_DEPRECATIONS_HELPER`` to higher number of deprecation notices is reached (``0`` is the default value). -You can even finer-grained control by using other keys of the ``max`` -array, which are ``internal``, ``direct``, and ``indirect``. The +You can have even finer-grained control by using other keys of the ``max`` +array, which are ``self``, ``direct``, and ``indirect``. The ``SYMFONY_DEPRECATIONS_HELPER`` environment variable accept a url-encoded string, meaning you can combine thresholds and any other configuration setting, like this: -``SYMFONY_DEPRECATIONS_HELPER=max[total]=42&max[internal]=0&verbose=0`` +``SYMFONY_DEPRECATIONS_HELPER=max[total]=42&max[self]=0&verbose=0`` Internal deprecations ..................... @@ -220,7 +220,7 @@ but: * forget to fix the deprecated calls if there are any; * forget to mark appropriate tests with the ``@group legacy`` annotations. -By using ``SYMFONY_DEPRECATIONS_HELPER=max[internal]=0``, +By using ``SYMFONY_DEPRECATIONS_HELPER=max[self]=0``, deprecations that are triggered outside the ``vendors`` directory will be accounted for seperately, while deprecations triggered from a library inside it will not (unless you reach 999999 of these), giving you @@ -233,12 +233,13 @@ When working on a project, you might be more interested in ``max[direct]``. 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 those (apart from a pull request on the outdated vendor). -This key allows you to put a threshold on direct deprecations only, -allowing you to notice when *your code* is using deprecated APIs, and to -keep up with the changes. You can of course still use ``max[indirect]`` -if you want to keep indirect deprecations under a given threshold. +fix deprecations as soon as possible, which means you should create a pull +request on the outdated vendor, and ignore these deprecations until your +pull request is merged. This key allows you to put a threshold on direct +deprecations only,allowing you to notice when *your code* is using +deprecated APIs, and to keep up with the changes. You can of course +still use ``max[indirect]`` if you want to keep indirect deprecations +under a given threshold. Here is a summary that should help you pick the right configuration: @@ -246,12 +247,12 @@ Here is a summary that should help you pick the right configuration: | Value | Recommended situation | +========================+=====================================================+ | max[total]=0 | Recommended for actively maintained projects | -| | with little to no dependencies | +| | with robust/no dependencies | +------------------------+-----------------------------------------------------+ | max[direct]=0 | Recommended for projects with dependencies | | | that fail to keep up with new deprecations. | +------------------------+-----------------------------------------------------+ -| max[internal]=0 | Recommended for libraries that use | +| max[self]=0 | Recommended for libraries that use | | | the deprecation system themselves and | | | cannot afford to use one of the modes above. | +------------------------+-----------------------------------------------------+ @@ -259,7 +260,7 @@ Here is a summary that should help you pick the right configuration: Disabling the verbose output ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, the brige will display a detailed output with the number of +By default, the bridge will display a detailed output with the number of deprecations and where they arise. If this is too much for you, you can use ``SYMFONY_DEPRECATIONS_HELPER=verbose=0`` to turn the verbose output off. From 7a29ae6ef2b3140f2496a9e711e286459748f5c3 Mon Sep 17 00:00:00 2001 From: Olena Kirichok Date: Sun, 28 Apr 2019 17:47:21 +0200 Subject: [PATCH 3/5] fixup! Document changes in the deprecation error handler --- components/phpunit_bridge.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index ae4764e8297..92e5ffe26f7 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -247,12 +247,12 @@ Here is a summary that should help you pick the right configuration: | Value | Recommended situation | +========================+=====================================================+ | max[total]=0 | Recommended for actively maintained projects | -| | with robust/no dependencies | +| | with robust/no dependencies | +------------------------+-----------------------------------------------------+ | max[direct]=0 | Recommended for projects with dependencies | | | that fail to keep up with new deprecations. | +------------------------+-----------------------------------------------------+ -| max[self]=0 | Recommended for libraries that use | +| max[self]=0 | Recommended for libraries that use | | | the deprecation system themselves and | | | cannot afford to use one of the modes above. | +------------------------+-----------------------------------------------------+ From 823360998b07b84bb716928f249f15ae99ef0bba Mon Sep 17 00:00:00 2001 From: Olena Kirichok Date: Mon, 29 Apr 2019 14:05:38 +0200 Subject: [PATCH 4/5] fixup! Document changes in the deprecation error handler --- components/phpunit_bridge.rst | 6 +++--- setup/upgrade_major.rst | 6 +++++- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index 92e5ffe26f7..108c3f22037 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -211,7 +211,7 @@ 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, +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=max[total]=999999`` because of this. This has the drawback of allowing contributions that introduce deprecations @@ -226,7 +226,7 @@ be accounted for seperately, while deprecations triggered from a library inside it will not (unless you reach 999999 of these), giving you the best of both worlds. -Direct and indirect deprecations +Direct and Indirect Deprecations ................................ When working on a project, you might be more interested in @@ -257,7 +257,7 @@ Here is a summary that should help you pick the right configuration: | | cannot afford to use one of the modes above. | +------------------------+-----------------------------------------------------+ -Disabling the verbose output +Disabling the Verbose Output ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, the bridge will display a detailed output with the number of diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst index 16fb2a5f9c7..c23db607260 100644 --- a/setup/upgrade_major.rst +++ b/setup/upgrade_major.rst @@ -112,7 +112,11 @@ done! - (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 phpunit``). + You can also execute the command like: + + .. code-block:: terminal + + $ SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 phpunit .. _upgrade-major-symfony-composer: From 5ad9edaa028da1565fbe7302ea3efdbe6d4d7c81 Mon Sep 17 00:00:00 2001 From: Olena Kirichok Date: Fri, 17 May 2019 16:58:40 +0200 Subject: [PATCH 5/5] fixup! Document changes in the deprecation error handler --- setup/upgrade_major.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst index c23db607260..d888d24bfbf 100644 --- a/setup/upgrade_major.rst +++ b/setup/upgrade_major.rst @@ -116,7 +116,7 @@ done! .. code-block:: terminal - $ SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 phpunit + $ SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 php ./bin/phpunit .. _upgrade-major-symfony-composer: