Skip to content

Commit 8c6c7bf

Browse files
webmozartwebmozart
committed
Simplified usage description
1 parent 6d9edf1 commit 8c6c7bf

File tree

1 file changed

+52
-120
lines changed

1 file changed

+52
-120
lines changed

‎contributing/code/bc.rst‎

Lines changed: 52 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
Our 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.
66
However, backwards compatibility comes in many different flavors.
77

88
This 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.
2626
Using 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 <[email protected]>
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
7243
following use cases:
7344

7445
============================================== ============== ==============
75-
Use Case Normal API
46+
Use Case Regular API
7647
============================================== ============== ==============
7748
Type hint against Yes Yes
7849
Call method Yes Yes
@@ -83,87 +54,37 @@ Add custom method parameter No [1]_ Yes
8354
Add 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 <[email protected]>
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
16384
following use cases:
16485

16586
============================================== ============== ==============
166-
Use Case Normal API
87+
Use Case Regular API
16788
============================================== ============== ==============
16889
Type hint against Yes Yes
16990
Create instance Yes Yes
@@ -183,9 +104,20 @@ Add custom method parameter No [1]_ Yes
183104
Add 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

191123
Working on Symfony Code
@@ -202,7 +134,7 @@ This table tells you which changes you are allowed to do when working on
202134
Symfony's interfaces:
203135

204136
============================================== ============== ==============
205-
Type of Change Normal API
137+
Type of Change Regular API
206138
============================================== ============== ==============
207139
Remove entirely No No
208140
Change name or namespace No No
@@ -231,7 +163,7 @@ This table tells you which changes you are allowed to do when working on
231163
Symfony's classes:
232164

233165
================================================== ============== ==============
234-
Type of Change Normal API
166+
Type of Change Regular API
235167
================================================== ============== ==============
236168
Remove entirely No No
237169
Make final Yes [2]_ No

0 commit comments

Comments
 (0)