11Our Backwards Compatibility Promise
22===================================
33
4- As of Symfony 2.3, we promise you backwards compatibility for all further 2.x
5- releases. Ensuring smooth upgrades of your projects is our first priority.
4+ As of Symfony 2.3, we promise you backwards compatibility (BC) for all further
5+ 2.x releases. Ensuring smooth upgrades of your projects is our first priority.
66However, backwards compatibility comes in many different flavors.
77
88This page has two different target audiences: If you are using Symfony, it will
@@ -26,53 +26,24 @@ section in order to guarantee smooth upgrades to all future 2.x versions.
2626Using Our Interfaces
2727~~~~~~~~~~~~~~~~~~~~
2828
29- Normal Interfaces
30- .................
29+ In Symfony, we distinguish between regular and API interfaces. API interfaces
30+ are marked with an `` @api `` tag in their source code. For example::
3131
32- All interfaces in the ``Symfony `` namespace are **safe for use **. That means
33- that:
32+ /**
33+ * HttpKernelInterface handles a Request to convert it to a Response.
34+ *
35+ * @author Fabien Potencier <fabien@symfony.com>
36+ *
37+ * @api
38+ */
39+ interface HttpKernelInterface
40+ {
3441
35- * You can type hint against the interface.
36-
37- * You can call any of the methods provided by the interface.
38-
39- However:
40-
41- * You cannot implement the interface. The interface may change, but all changes
42- will be documented in the UPGRADE file.
43-
44-
45- API Interfaces
46- ..............
47-
48- All interfaces tagged with ``@api `` are also **safe for implementation **. That
49- means that:
50-
51- * You can implement the interface.
52-
53-
54- Internal Interfaces
55- ...................
56-
57- Interfaces or interface methods tagged with ``@internal `` are meant for internal
58- use in Symfony only. You should never use nor implement them.
59-
60-
61- Deprecated Interfaces
62- .....................
63-
64- Interfaces or interface methods tagged with ``@deprecated `` will be removed in
65- a future Symfony version. You should never use nor implement them.
66-
67-
68- Guarantee Details
69- .................
70-
71- When using our interfaces, we guarantee full backwards compatibility for the
42+ When using these interfaces, we guarantee full backwards compatibility for the
7243following use cases:
7344
7445============================================== ============== ==============
75- Use Case Normal API
46+ Use Case Regular API
7647============================================== ============== ==============
7748Type hint against Yes Yes
7849Call method Yes Yes
@@ -83,87 +54,37 @@ Add custom method parameter No [1]_ Yes
8354Add parameter default value Yes Yes
8455============================================== ============== ==============
8556
86- If you need to do any of the things marked with "No" above, feel free to
87- ask us whether the ``@api `` tag can be added on the respective Symfony code.
88- For that, simply open a `new ticket on GitHub `_.
89-
90-
91- Using Our Classes
92- ~~~~~~~~~~~~~~~~~
93-
94- Normal Classes
95- ..............
96-
97- All classes in the ``Symfony `` namespace are **safe for use **. That means that:
98-
99- * You can type hint against the class' name.
100-
101- * You can create new instances.
102-
103- * You can extend the class.
104-
105- * You can access public properties.
106-
107- * You can call public methods.
108-
109- When extending the class:
110-
111- * You can override public properties.
112-
113- However:
114-
115- * You cannot override methods in extending classes. The class may change, but
116- all changes will be documented in the UPGRADE file.
117-
118-
119- API Classes
120- ...........
121-
122- All classes tagged with ``@api `` are also **safe for extension **. That means
123- that:
124-
125- * You can access protected properties and methods.
126-
127- * You can call protected methods.
128-
129- * You can override protected properties.
130-
131- * You can override public and protected methods.
132-
133- Properties and methods tagged with ``@api `` are treated as if they belonged
134- to an API class. That means that you can call or override them regardless of
135- whether their class has the ``@api `` tag or not.
136-
137-
138- Internal Classes
139- ................
140-
141- Classes, properties and methods tagged with ``@internal `` are meant for internal
142- use in Symfony only. You should never use nor extend them.
143-
144-
145- Deprecated Classes
146- ..................
57+ .. note ::
14758
148- Classes, properties and methods tagged with ``@deprecated `` will be removed in
149- a future Symfony version. You should never use nor extend them.
59+ If you need to do any of the things marked with "No" above, feel free to
60+ ask us whether the ``@api `` tag can be added on the respective Symfony code.
61+ For that, simply open a `new ticket on GitHub `_.
15062
63+ Interfaces or interface methods tagged with ``@internal `` should never be
64+ implemented or used.
15165
152- Test Classes
153- ............
15466
155- All classes located in the various `` *\\Tests\\ `` namespaces are meant for
156- internal use only. You should never create, extend or call them directly.
67+ Using Our Classes
68+ ~~~~~~~~~~~~~~~~~
15769
70+ Just like with interfaces, we also distinguish between regular and API classes.
71+ Like API interfaces, API classes are marked with an ``@api `` tag::
15872
159- Guarantee Details
160- .................
73+ /**
74+ * Request represents an HTTP request.
75+ *
76+ * @author Fabien Potencier <fabien@symfony.com>
77+ *
78+ * @api
79+ */
80+ class Request
81+ {
16182
162- When using our classes, we guarantee full backwards compatibility for the
83+ When using these classes, we guarantee full backwards compatibility for the
16384following use cases:
16485
16586============================================== ============== ==============
166- Use Case Normal API
87+ Use Case Regular API
16788============================================== ============== ==============
16889Type hint against Yes Yes
16990Create instance Yes Yes
@@ -183,9 +104,20 @@ Add custom method parameter No [1]_ Yes
183104Add parameter default value Yes Yes
184105============================================== ============== ==============
185106
186- If you need to do any of the things marked with "No" above, feel free to
187- ask us whether the ``@api `` tag can be added on the respective Symfony code.
188- For that, simply open a `new ticket on GitHub `_.
107+ .. note ::
108+
109+ If you need to do any of the things marked with "No" above, feel free to
110+ ask us whether the ``@api `` tag can be added on the respective Symfony code.
111+ For that, simply open a `new ticket on GitHub `_.
112+
113+ In some cases, only specific properties and methods are tagged with the ``@api ``
114+ tag, even though their class is not. In these cases, we guarantee full backwards
115+ compatibility for the tagged properties and methods (as indicated in the column
116+ "API" above), but not for the rest of the class.
117+
118+ Classes, properties and methods tagged with ``@internal `` should never be
119+ created, extended or called directly. The same applies to all classes located in
120+ the various ``*\\Tests\\ `` namespaces.
189121
190122
191123Working on Symfony Code
@@ -202,7 +134,7 @@ This table tells you which changes you are allowed to do when working on
202134Symfony's interfaces:
203135
204136============================================== ============== ==============
205- Type of Change Normal API
137+ Type of Change Regular API
206138============================================== ============== ==============
207139Remove entirely No No
208140Change name or namespace No No
@@ -231,7 +163,7 @@ This table tells you which changes you are allowed to do when working on
231163Symfony's classes:
232164
233165================================================== ============== ==============
234- Type of Change Normal API
166+ Type of Change Regular API
235167================================================== ============== ==============
236168Remove entirely No No
237169Make final Yes [2 ]_ No
0 commit comments