8000 minor #5413 Fix doc about deprecations policy (nicolas-grekas) · symfony/symfony-docs@3905acb · GitHub
[go: up one dir, main page]
Skip to content

Commit 3905acb

Browse files
weaverryanweaverryan
committed
minor #5413 Fix doc about deprecations policy (nicolas-grekas)
This PR was merged into the 2.7 branch. Discussion ---------- Fix doc about deprecations policy | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | ~2.7 | Fixed tickets | - Commits ------- 966be4a Fix doc about deprecations policy
2 parents 07b7c72 + 966be4a commit 3905acb

File tree

5 files changed

+28
-83
lines changed

5 files changed

+28
-83
lines changed

‎contributing/code/conventions.rst‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to
9292
relevant classes, methods, properties, ...::
9393

9494
/**
95-
* @deprecated Deprecated since version 2.X, to be removed in 2.Y. Use XXX instead.
95+
* @deprecated Deprecated since version 2.8, to be removed in 3.0. Use XXX instead.
9696
*/
9797

9898
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
103103
the migration starting one or two minor versions before the version where the
104104
feature will be removed (depending on the criticality of the removal)::
105105

106-
trigger_error('XXX() is deprecated since version 2.X and will be removed in 2.Y. Use XXX instead.', E_USER_DEPRECATED);
106+
@trigger_error('XXX() is deprecated since version 2.8 and will be removed in 3.0. Use XXX instead.', E_USER_DEPRECATED);
107+
108+
Without the `@-silencing operator`_, users would need to opt-out from deprecation
109+
notices. Silencing swaps this behavior and allows users to opt-in when they are
110+
ready to cope with them (by adding a custom error handler like the one used by
111+
the Web Debug Toolbar or by the PHPUnit bridge).
112+
113+
.. _`@-silencing operator`: https://php.net/manual/en/language.operators.errorcontrol.php

‎cookbook/map.rst.inc‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,6 @@
238238
* :doc:`/cookbook/upgrade/patch_version`
239239
* :doc:`/cookbook/upgrade/minor_version`
240240
* :doc:`/cookbook/upgrade/major_version`
241-
* :doc:`/cookbook/upgrade/deprecation_warnings`
242241

243242
* :doc:`/cookbook/validation/index`
244243

‎cookbook/upgrade/deprecation_warnings.rst‎

Lines changed: 0 additions & 74 deletions
This file was deleted.

‎cookbook/upgrade/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,3 @@ There are three types of upgrades, all needing a little different preparation:
1616
/cookbook/upgrade/patch_version
1717
/cookbook/upgrade/minor_version
1818
/cookbook/upgrade/major_version
19-
/cookbook/upgrade/deprecation_warnings

‎cookbook/upgrade/major_version.rst‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ There are a couple of steps to upgrading a major version:
2626
During the lifecycle of a major release, new features are added and method
2727
signatures and public API usages are changed. However,
2828
:doc:`minor versions </cookbook/upgrade/minor_version>` should not contain any
29-
backwards compatibility changes. To accomplish this, the "old" (e.g. functions,
29+
backwards incompatible changes. To accomplish this, the "old" (e.g. functions,
3030
classes, etc) code still works, but is marked as *deprecated*, indicating that
3131
it will be removed/changed in the future and that you should stop using it.
3232

@@ -35,13 +35,27 @@ functionality are removed. So, as long as you've updated your code to stop
3535
using these deprecated features in the last version before the major (e.g.
3636
2.8.*), you should be able to upgrade without a problem.
3737

38-
To help you with this, the last minor releases will trigger deprecated notices.
39-
For example, 2.7 and 2.8 trigger deprecated notices. When visiting your
40-
application in the :doc:`dev environment </cookbook/configuration/environments>`
38+
To help you with this, deprecation notices are triggered whenever you end up
39+
using a deprecated feature. When visiting your application in the
40+
:doc:`dev environment </cookbook/configuration/environments>`
4141
in your browser, these notices are shown in the web dev toolbar:
4242

4343
.. image:: /images/cookbook/deprecations-in-profiler.png
4444

45+
Of course ultimately, you want to stop using the deprecated functionality.
46+
Sometimes, this is easy: the warning might tell you exactly what to change.
47+
48+
But other times, the warning might be unclear: a setting somewhere might
49+
cause a class deeper to trigger the warning. In this case, Symfony does its
50+
best to give a clear message, but you may need to research that warning further.
51+
52+
And sometimes, the warning may come from a third-party library or bundle
53+
that you're using. If that's true, there's a good chance that those deprecations
54+
have already been updated. In that case, upgrade the library to fix them.
55+
56+
Once all the deprecation warnings are gone, you can upgrade with a lot
57+
more confidence.
58+
4559
Deprecations in PHPUnit
4660
~~~~~~~~~~~~~~~~~~~~~~~
4761

@@ -52,7 +66,7 @@ To make sure this doesn't happen, you can install the PHPUnit bridge:
5266

5367
.. code-block:: bash
5468
55-
$ composer require symfony/phpunit-bridge
69+
$ composer require --dev symfony/phpunit-bridge
5670
5771
Now, your tests execute normally and a nice summary of the deprecation notices
5872
is displayed at the end of the test report:

0 commit comments

Comments
 (0)
0