Merge branch 'fabpot-deprecations' into 2.0

Author: weaverryan

contributing/code/conventions.rst

@@ -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
+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
+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);

contributing/code/patches.rst

@@ -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;

contributing/community/releases.rst

@@ -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
+deprecations are handled in Symfony.
+
 Rationale
 ---------