Skip to content

Fix doc about deprecations policy #5413

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 25, 2015
Merged

Fix doc about deprecations policy #5413

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions contributing/code/conventions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
1 change: 0 additions & 1 deletion cookbook/map.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down
74 changes: 0 additions & 74 deletions cookbook/upgrade/deprecation_warnings.rst
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion cookbook/upgrade/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
24 changes: 19 additions & 5 deletions cookbook/upgrade/major_version.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 </cookbook/upgrade/minor_version>` 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.

Expand All @@ -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 </cookbook/configuration/environments>`
To help you with this, deprecation notices are triggered whenever you end up
using a deprecated feature. When visiting your application in the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we now immediately trigger deprecated notices whenever something is deprecated? (in 3.1 for example?) Otherwise, I propose to readd the versions in this sentence.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that we now silence them by default, I think we could. but we would have to discuss this with the core team

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an obvious Yes to me, let's talk about it at the next meeting you're right !

:doc:`dev environment </cookbook/configuration/environments>`
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
~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -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:
Expand Down