Skip to content

Commit e11335f

Browse files
webmozartwebmozart
committed
Improved the wording of the "Using Symfony" section
1 parent 4868452 commit e11335f

File tree

1 file changed

+111
-81
lines changed

1 file changed

+111
-81
lines changed

‎contributing/code/bc.rst

+111-81
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,42 @@
11
Our Backwards Compatibility Promise
22
===================================
33

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.
6-
However, backwards compatibility comes in many different flavors.
4+
If you are using Symfony, we promise you backwards compatibility (BC) for all
5+
major releases (2.x, 3.x, ...). Ensuring smooth upgrades of your projects is our
6+
first priority. However, backwards compatibility comes in many different flavors.
7+
8+
.. note::
9+
10+
This promise was introduced with Symfony 2.3 and does not apply to previous
11+
versions of Symfony.
712

813
This page has two different target audiences: If you are using Symfony, it will
914
tell you how to make sure that you will be able to upgrade smoothly to all
1015
future 2.x versions. If you are contributing to Symfony, this page will tell you
1116
the rules that you need to follow to ensure smooth upgrades for our users.
1217

13-
.. note::
14-
15-
This promise is in trial until April 15th, 2014. Until then, we may change
16-
parts of it if we discover problems or limitations.
17-
18-
1918
Using Symfony Code
2019
------------------
2120

22-
You are using Symfony in your projects? Then stick to the guidelines in this
23-
section in order to guarantee smooth upgrades to all future 2.x versions.
24-
21+
If you are using Symfony in your projects, the following guidelines will help
22+
you to ensure smooth upgrades to all future minor releases of Symfony (such as
23+
2.5, 2.6 and so on).
2524

2625
Using Our Interfaces
2726
~~~~~~~~~~~~~~~~~~~~
2827

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::
28+
All interfaces shipped with Symfony can be used in type hints. You can also call
29+
any of the methods that they declare. We guarantee that we won't break code that
30+
sticks to these rules.
31+
32+
.. note::
33+
34+
The exception to this rule are interfaces tagged with ``@internal``. Such
35+
interfaces should never be used or implemented.
36+
37+
If you want to implement an interface, you should first make sure that the
38+
interface is an API interface. You can recognize API interfaces by the ``@api``
39+
tag in their source code::
3140

3241
/**
3342
* HttpKernelInterface handles a Request to convert it to a Response.
@@ -39,40 +48,51 @@ are marked with an ``@api`` tag in their source code. For example::
3948
interface HttpKernelInterface
4049
{
4150

42-
In simple words, the difference between regular and API interfaces is that you
43-
can implement API interfaces yourself and we will guarantee full backwards
44-
compatibility. The same is not true for regular interfaces: We may, for example,
45-
add an optional parameter or a new method to them and thus break your own
46-
implementation.
47-
48-
In detail, we guarantee full backwards compatibility for the following use
49-
cases:
50-
51-
============================================== ============== ==============
52-
Use Case Regular API
53-
============================================== ============== ==============
54-
Type hint against Yes Yes
55-
Call method Yes Yes
56-
**In Implementing Classes**
57-
Implement method No [1]_ Yes
58-
Add custom method No [1]_ Yes
59-
Add custom method parameter No [1]_ Yes
60-
Add parameter default value Yes Yes
61-
============================================== ============== ==============
51+
If you implement an API interface, we promise that we won't ever break your
52+
code. Regular interfaces, by contrast, should never be implemented, because if
53+
we add a new method to the interface or add a new optional parameter to the
54+
signature of a method, we would generate a fatal error in your application.
55+
56+
The following table explains in detail which use cases are covered by our
57+
backwards compatibility promise:
58+
59+
+-----------------------------------------------+---------------+---------------+
60+
| Use Case | Regular | API |
61+
+-----------------------------------------------+---------------+---------------+
62+
| If you... | Then we guarantee BC... |
63+
+===============================================+===============+===============+
64+
| Type hint against the interface | Yes | Yes |
65+
+-----------------------------------------------+---------------+---------------+
66+
| Call a method | Yes | Yes |
67+
+-----------------------------------------------+---------------+---------------+
68+
| **If you implement the interface and...** | **Then we guarantee BC...** |
69+
+-----------------------------------------------+---------------+---------------+
70+
| Implement a method | No [1]_ | Yes |
71+
+-----------------------------------------------+---------------+---------------+
72+
| Add a parameter to an implemented method | No [1]_ | Yes |
73+
+-----------------------------------------------+---------------+---------------+
74+
| Add a default value to a parameter | Yes | Yes |
75+
+-----------------------------------------------+---------------+---------------+
6276

6377
.. note::
6478

65-
If you need to do any of the things marked with "No" above, feel free to
66-
ask us whether the ``@api`` tag can be added on the respective Symfony code.
67-
For that, simply open a `new ticket on GitHub`_.
68-
69-
Interfaces or interface methods tagged with ``@internal`` should never be
70-
implemented or used.
71-
79+
If you think that one of our regular interfaces should have an ``@api`` tag,
80+
put your request into a `new ticket on GitHub`_. We will then evaluate
81+
whether we can add the tag or not.
7282

7383
Using Our Classes
7484
~~~~~~~~~~~~~~~~~
7585

86+
All classes provided by Symfony may be instantiated and accessed through their
87+
public methods and properties.
88+
89+
.. note::
90+
91+
Classes, properties and methods that bear the tag ``@internal`` as well as
92+
the classes located in the various ``*\\Tests\\`` namespaces are an
93+
exception to this rule. They are meant for internal use only and should not
94+
be accessed by your own code.
95+
7696
Just like with interfaces, we also distinguish between regular and API classes.
7797
Like API interfaces, API classes are marked with an ``@api`` tag::
7898

@@ -87,57 +107,69 @@ Like API interfaces, API classes are marked with an ``@api`` tag::
87107
{
88108

89109
The difference between regular and API classes is that we guarantee full
90-
backwards compatibility if you extend an API class and override its methods,
91-
but not for regular classes. In regular classes, we may for example add an
92-
optional parameter to a method and thus break your overridden method.
93-
94-
Again, here are the details about which use cases we guarantee full backwards
95-
compatibility for:
96-
97-
============================================== ============== ==============
98-
Use Case Regular API
99-
============================================== ============== ==============
100-
Type hint against Yes Yes
101-
Create instance Yes Yes
102-
Extend Yes Yes
103-
Access public property Yes Yes
104-
Call public method Yes Yes
105-
**In Extending Classes**
106-
Access protected property No [1]_ Yes
107-
Call protected method No [1]_ Yes
108-
Override public property Yes Yes
109-
Override protected property No [1]_ Yes
110-
Override public method No [1]_ Yes
111-
Override protected method No [1]_ Yes
112-
Add custom property No No
113-
Add custom method No No
114-
Add custom method parameter No [1]_ Yes
115-
Add parameter default value Yes Yes
116-
============================================== ============== ==============
117-
118-
.. note::
119-
120-
If you need to do any of the things marked with "No" above, feel free to
121-
ask us whether the ``@api`` tag can be added on the respective Symfony code.
122-
For that, simply open a `new ticket on GitHub`_.
110+
backwards compatibility if you extend an API class and override its methods. We
111+
can't give the same promise for regular classes, because there we may, for
112+
example, add an optional parameter to a method. Consequently, the signature of
113+
your overridden method won't match anymore and generate a fatal error.
123114

124115
In some cases, only specific properties and methods are tagged with the ``@api``
125116
tag, even though their class is not. In these cases, we guarantee full backwards
126117
compatibility for the tagged properties and methods (as indicated in the column
127-
"API" above), but not for the rest of the class.
118+
"API" below), but not for the rest of the class.
119+
120+
To be on the safe side, check the following table to know which use cases are
121+
covered by our backwards compatibility promise:
122+
123+
+-----------------------------------------------+---------------+---------------+
124+
| Use Case | Regular | API |
125+
+-----------------------------------------------+---------------+---------------+
126+
| If you... | Then we guarantee BC... |
127+
+===============================================+===============+===============+
128+
| Type hint against the class | Yes | Yes |
129+
+-----------------------------------------------+---------------+---------------+
130+
| Create a new instance | Yes | Yes |
131+
+-----------------------------------------------+---------------+---------------+
132+
| Extend the class | Yes | Yes |
133+
+-----------------------------------------------+---------------+---------------+
134+
| Access a public property | Yes | Yes |
135+
+-----------------------------------------------+---------------+---------------+
136+
| Call a public method | Yes | Yes |
137+
+-----------------------------------------------+---------------+---------------+
138+
| **If you extend the class and...** | **Then we guarantee BC...** |
139+
+-----------------------------------------------+---------------+---------------+
140+
| Access a protected property | No [1]_ | Yes |
141+
+-----------------------------------------------+---------------+---------------+
142+
| Call a protected methods | No [1]_ | Yes |
143+
+-----------------------------------------------+---------------+---------------+
144+
| Override a public property | Yes | Yes |
145+
+-----------------------------------------------+---------------+---------------+
146+
| Override a protected property | No [1]_ | Yes |
147+
+-----------------------------------------------+---------------+---------------+
148+
| Override a public method | No [1]_ | Yes |
149+
+-----------------------------------------------+---------------+---------------+
150+
| Override a protected method | No [1]_ | Yes |
151+
+-----------------------------------------------+---------------+---------------+
152+
| Add a new property | No | No |
153+
+-----------------------------------------------+---------------+---------------+
154+
| Add a new method | No | No |
155+
+-----------------------------------------------+---------------+---------------+
156+
| Add a parameter to an overridden method | No [1]_ | Yes |
157+
+-----------------------------------------------+---------------+---------------+
158+
| Add a default value to a parameter | Yes | Yes |
159+
+-----------------------------------------------+---------------+---------------+
128160

129-
Classes, properties and methods tagged with ``@internal`` should never be
130-
created, extended or called directly. The same applies to all classes located in
131-
the various ``*\\Tests\\`` namespaces.
161+
.. note::
132162

163+
If you think that one of our regular classes should have an ``@api`` tag,
164+
put your request into a `new ticket on GitHub`_. We will then evaluate
165+
whether we can add the tag or not.
133166

134167
Working on Symfony Code
135168
-----------------------
136169

137170
Do you want to help us improve Symfony? That's great! However, please stick
138171
to the rules listed below in order to ensure smooth upgrades for our users.
139172

140-
141173
Changing Interfaces
142174
~~~~~~~~~~~~~~~~~~~
143175

@@ -166,7 +198,6 @@ Change parameter type Yes [2]_ [4]_ No
166198
Change return type Yes [2]_ [5]_ No
167199
============================================== ============== ==============
168200

169-
170201
Changing Classes
171202
~~~~~~~~~~~~~~~~
172203

@@ -226,7 +257,6 @@ Change parameter type Yes [2]_ [4]_ No
226257
Change return type Yes [2]_ [5]_ No
227258
================================================== ============== ==============
228259

229-
230260
.. [1] Your code may be broken by changes in the Symfony code. Such changes will
231261
however be documented in the UPGRADE file.
232262

0 commit comments

Comments
 (0)