From 966be4a6caa61cd9f9890336de8cb338dc3b1c5e Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Fri, 19 Jun 2015 10:25:37 +0200 Subject: [PATCH] Fix doc about deprecations policy --- contributing/code/conventions.rst | 11 +++- cookbook/map.rst.inc | 1 - cookbook/upgrade/deprecation_warnings.rst | 74 ----------------------- cookbook/upgrade/index.rst | 1 - cookbook/upgrade/major_version.rst | 24 ++++++-- 5 files changed, 28 insertions(+), 83 deletions(-) delete mode 100644 cookbook/upgrade/deprecation_warnings.rst diff --git a/contributing/code/conventions.rst b/contributing/code/conventions.rst index e48eebd414e..4e698f5a182 100644 --- a/contributing/code/conventions.rst +++ b/contributing/code/conventions.rst @@ -92,7 +92,7 @@ A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to relevant classes, methods, properties, ...:: /** - * @deprecated Deprecated since version 2.X, to be removed in 2.Y. Use XXX instead. + * @deprecated Deprecated since version 2.8, to be removed in 3.0. Use XXX instead. */ The deprecation message should indicate the version when the class/method was @@ -103,4 +103,11 @@ A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with the migration starting one or two minor versions before the version where the feature will be removed (depending on the criticality of the removal):: - trigger_error('XXX() is deprecated since version 2.X and will be removed in 2.Y. Use XXX instead.', E_USER_DEPRECATED); + @trigger_error('XXX() is deprecated since version 2.8 and will be removed in 3.0. Use XXX instead.', E_USER_DEPRECATED); + +Without the `@-silencing operator`_, users would need to opt-out from deprecation +notices. Silencing swaps this behavior and allows users to opt-in when they are +ready to cope with them (by adding a custom error handler like the one used by +the Web Debug Toolbar or by the PHPUnit bridge). + +.. _`@-silencing operator`: https://php.net/manual/en/language.operators.errorcontrol.php diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 691c9a71d73..4316f0de726 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -224,7 +224,6 @@ * :doc:`/cookbook/upgrade/patch_version` * :doc:`/cookbook/upgrade/minor_version` * :doc:`/cookbook/upgrade/major_version` - * :doc:`/cookbook/upgrade/deprecation_warnings` * :doc:`/cookbook/validation/index` diff --git a/cookbook/upgrade/deprecation_warnings.rst b/cookbook/upgrade/deprecation_warnings.rst deleted file mode 100644 index 12e6c21c7e9..00000000000 --- a/cookbook/upgrade/deprecation_warnings.rst +++ /dev/null @@ -1,74 +0,0 @@ -What do these "XXX is deprecated " E_USER_DEPRECATED Warnings mean? -=================================================================== - -Starting in Symfony 2.7, if you use a deprecated class, function or option, -Symfony triggers an ``E_USER_DEPRECATED`` error. Internally, that looks something -like this:: - - trigger_error( - 'The fooABC method is deprecated since version 2.4 and will be removed in 3.0.', - E_USER_DEPRECATED - ); - -This is great, because you can check your logs to know what needs to change -before you upgrade. In the Symfony Framework, the number of deprecated calls -shows up in the web debug toolbar. And if you install the `phpunit-bridge`_, -you can get a report of deprecated calls after running your tests. - -How can I Silence the Warnings? -------------------------------- - -As useful as these are, you don't want them to show up while developing and -you may also want to silence them on production to avoid filling up your -error logs. - -In the Symfony Framework -~~~~~~~~~~~~~~~~~~~~~~~~ - -In the Symfony Framework, ``~E_USER_DEPRECATED`` is added to ``app/bootstrap.php.cache`` -automatically, but you need at least version 2.3.14 or 3.0.21 of the -`SensioDistributionBundle`_. So, you may need to upgrade: - -.. code-block:: bash - - $ composer update sensio/distribution-bundle - -Once you've updated, the ``bootstrap.php.cache`` file is rebuilt automatically. -At the top, you should see a line adding ``~E_USER_DEPRECATED``. - -Outside of the Symfony Framework -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To do that, add ``~E_USER_DEPRECATED`` to your ``error_reporting`` -setting in ``php.ini``: - -.. code-block:: ini - - ; before - error_reporting = E_ALL - ; after - error_reporting = E_ALL & ~E_USER_DEPRECATED - -Alternatively, you can set this directly in bootstrap of your project:: - - error_reporting(error_reporting() & ~E_USER_DEPRECATED); - -How can I Fix the Warnings? ---------------------------- - -Of course ultimately, you want to stop using the deprecated functionality. -Sometimes, this is easy: the warning might tell you exactly what to change. - -But other times, the warning might be unclear: a setting somewhere might -cause a class deeper to trigger the warning. In this case, Symfony does its -best to give a clear message, but you may need to research that warning further. - -And sometimes, the warning may come from a third-party library or bundle -that you're using. If that's true, there's a good chance that those deprecations -have already been updated. In that case, upgrade the library to fix them. - -Once all the deprecation warnings are gone, you can upgrade with a lot -more confidence. - -.. _`phpunit-bridge`: https://github.com/symfony/phpunit-bridge -.. _`SensioDistributionBundle`: https://github.com/sensiolabs/SensioDistributionBundle diff --git a/cookbook/upgrade/index.rst b/cookbook/upgrade/index.rst index 3a37aa78a61..b943f2ae32a 100644 --- a/cookbook/upgrade/index.rst +++ b/cookbook/upgrade/index.rst @@ -16,4 +16,3 @@ There are three types of upgrades, all needing a little different preparation: /cookbook/upgrade/patch_version /cookbook/upgrade/minor_version /cookbook/upgrade/major_version - /cookbook/upgrade/deprecation_warnings diff --git a/cookbook/upgrade/major_version.rst b/cookbook/upgrade/major_version.rst index 0c5107b6fed..8ff9ff51f6b 100644 --- a/cookbook/upgrade/major_version.rst +++ b/cookbook/upgrade/major_version.rst @@ -26,7 +26,7 @@ There are a couple of steps to upgrading a major version: During the lifecycle of a major release, new features are added and method signatures and public API usages are changed. However, :doc:`minor versions ` should not contain any -backwards compatibility changes. To accomplish this, the "old" (e.g. functions, +backwards incompatible changes. To accomplish this, the "old" (e.g. functions, classes, etc) code still works, but is marked as *deprecated*, indicating that it will be removed/changed in the future and that you should stop using it. @@ -35,13 +35,27 @@ functionality are removed. So, as long as you've updated your code to stop using these deprecated features in the last version before the major (e.g. 2.8.*), you should be able to upgrade without a problem. -To help you with this, the last minor releases will trigger deprecated notices. -For example, 2.7 and 2.8 trigger deprecated notices. When visiting your -application in the :doc:`dev environment ` +To help you with this, deprecation notices are triggered whenever you end up +using a deprecated feature. When visiting your application in the +:doc:`dev environment ` in your browser, these notices are shown in the web dev toolbar: .. image:: /images/cookbook/deprecations-in-profiler.png +Of course ultimately, you want to stop using the deprecated functionality. +Sometimes, this is easy: the warning might tell you exactly what to change. + +But other times, the warning might be unclear: a setting somewhere might +cause a class deeper to trigger the warning. In this case, Symfony does its +best to give a clear message, but you may need to research that warning further. + +And sometimes, the warning may come from a third-party library or bundle +that you're using. If that's true, there's a good chance that those deprecations +have already been updated. In that case, upgrade the library to fix them. + +Once all the deprecation warnings are gone, you can upgrade with a lot +more confidence. + Deprecations in PHPUnit ~~~~~~~~~~~~~~~~~~~~~~~ @@ -52,7 +66,7 @@ To make sure this doesn't happen, you can install the PHPUnit bridge: .. code-block:: bash - $ composer require symfony/phpunit-bridge + $ composer require --dev symfony/phpunit-bridge Now, your tests execute normally and a nice summary of the deprecation notices is displayed at the end of the test report: