feature #3439 [Review] Added detailed Backwards Compatibility Promise…

… text (webmozart)

This PR was merged into the 2.1 branch.

Discussion
----------

[Review] Added detailed Backwards Compatibility Promise text

I created a detailed text about which parts of the Symfony code are covered by our BC promise. The goals are to:

* tell our users which parts exactly are safe to use
* tell our contributors which changes they are allowed to do

I'll continue working on the individual rules of allowed changes. Nevertheless, let me hear your feedback.

##### Update (2014/01/10)

The draft is ready for review now.

Commits
-------

0717192 Removed useless line break
ce58ee9 Added rules for adding parent interfaces and moving methods/properties to parent interfaces/classes
be2251c Implemented @fabpot's comments
90c4de6 Mentioned Semantic Versioning in the introduction
2320906 Extracted duplicated text into _api_tagging.rst.inc
bdd3c03 Implemented changes suggested by @wouterj
fd1d912 Typo
11bb879 Grammar
25443c0 Improved table formatting
e11335f Improved the wording of the "Using Symfony" section
4868452 Added prose about the difference between regular/API classes/interfaces
8c6c7bf Simplified usage description
6d9edf1 Improved wording: Changed "safe" to "guaranteed"
ef1f021 Added note about test classes
5a160c5 Added note about deprecated interfaces/classes
69768dd Improved wording: use -> call, access
0c6420f Added information about changing parameter types
6501a35 Added information about changing return types that are classes or interfaces
dfb3e8b Improved wording
be76644 Added information about internal classes and interfaces
af3a645 Added note about requesting `@api` tags
dcbe79a Improved wording
efd3911 Added that adding custom properties is not safe
00c6ebe Fixed safety statements
54fd836 Language improvements
db76288 Fixed headings
c6e850d Language fixes
4c5a55d Rearranged page to have different sections for different user bases
502ed95 Added: Some breaking changes to unsafe operations are documented in the UPGRADE file
31ab2db Improved wording
a3ad08c Removed most of the "cannot" statements which are repeated in the tables now
345410c Rearranged safe operations to make more sense
afadaab Changed: The last parameters of a method may be removed
44ecf16 Fixed: No parameters must be added (ever) to API class methods
0e925cb Added tables with safe operations
79ca9f7 Added information about type compatibility
dacd7ce Rearranged rules to be more easily understandable
7320ed0 Updated BC promise to be valid as of Symfony 2.3
840073c Added detailed BC promise text

contributing/code/_api_tagging.rst.inc

@@ -0,0 +1,7 @@
+.. note::
+
+    If you think that one of our regular classes should have an ``@api`` tag,
+    put your request into a `new ticket on GitHub`_. We will then evaluate
+    whether we can add the tag or not.
+
+.. _new ticket on GitHub: https://github.com/symfony/symfony/issues/new