Skip to content

added information about how deprecations work #2246

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
Feb 23, 2013
Merged

added information about how deprecations work #2246

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
26 changes: 26 additions & 0 deletions contributing/code/conventions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,3 +76,29 @@ must be used instead (where ``XXX`` is the name of the related thing):
difference: "setXXX" may replace, or add new elements to the relation.
"replaceXXX", on the other hand, cannot add new elements. If an unrecognized
key as passed to "replaceXXX" it must throw an exception.

Deprecations
------------

From time to time, some classes and/or methods are deprecated 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.

And think this should also be replaced with classes, methods, properties, constants, ect.?

Copy link
Member Author

Choose a reason for hiding this comment

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

no, as you deprecate a feature that is implemented in classes/methods.

Copy link
Contributor

Choose a reason for hiding this comment

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

I don't get why ie constants or interfaces would not be valid cases here also

Copy link
Member Author

Choose a reason for hiding this comment

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

Because a feature cannot be made of constants only. You are nitpicking here.

Copy link
Contributor

Choose a reason for hiding this comment

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

They are times when we only deprecate a constant / option (ie form).

I think interfaces are at least non disputable.

framework; that happens when a feature implementation cannot be changed
because of backward compatibility issues, but we still want to propose a
"better" alternative. In that case, the old implementation can simply be
**deprecated**.

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.
*/

The deprecation message should indicate the version when the class/method was
Copy link
Member

Choose a reason for hiding this comment

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

same here?

deprecated, the version when it will be removed, and whenever possible, how
the feature was replaced.

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 of 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);
Copy link
Member

Choose a reason for hiding this comment

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

I like to break long lines to avoid horizontal scrolling bars, we could replace this by:

    trigger_error(
        'XXX() is deprecated since version 2.X and will be removed in 2.Y. Use XXX instead.',
        E_USER_DEPRECATED
    )

5 changes: 3 additions & 2 deletions contributing/code/patches.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,8 +153,9 @@ Work on your Patch
Work on the code as much as you want and commit as much as you want; but keep
in mind the following:

* Follow the coding :doc:`standards <standards>` (use `git diff --check` to
check for trailing spaces -- also read the tip below);
* Read about the Symfony :doc:`conventions <conventions>` and follow the
coding :doc:`standards <standards>` (use `git diff --check` to check for
trailing spaces -- also read the tip below);

* Add unit tests to prove that the bug is fixed or that the new feature
actually works;
Expand Down
9 changes: 9 additions & 0 deletions contributing/community/releases.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,15 @@ be scheduled for the next major version: Symfony 3.0.
The work on Symfony 3.0 will start whenever enough major features breaking
backward compatibility are waiting on the todo-list.

Deprecations
------------

When a feature implementation cannot be replaced with a better one without
breaking backward compatibility, there is still the possibility to deprecate
the old implementation and add a new preferred one along side. Read the
:doc:`conventions <../code/conventions>` document to learn more about how
Copy link
Member

Choose a reason for hiding this comment

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

The link should go to the section itself instead of the beginning of the page

deprecations are handled in Symfony.

Rationale
---------

Expand Down