Skip to content

Commit be2251c

Browse files
webmozartwebmozart
committed
Implemented @fabpot's comments
1 parent 90c4de6 commit be2251c

File tree

1 file changed

+71
-37
lines changed

1 file changed

+71
-37
lines changed

‎contributing/code/bc.rst

Lines changed: 71 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ sticks to these rules.
5050
.. caution::
5151

5252
The exception to this rule are interfaces tagged with ``@internal``. Such
53-
interfaces should *never* be used or implemented.
53+
interfaces should not be used or implemented.
5454

5555
If you want to implement an interface, you should first make sure that the
5656
interface is an API interface. You can recognize API interfaces by the ``@api``
@@ -69,9 +69,15 @@ tag in their source code::
6969
}
7070

7171
If you implement an API interface, we promise that we won't ever break your
72-
code. Regular interfaces, by contrast, should never be implemented, because if
73-
we add a new method to the interface or add a new optional parameter to the
74-
signature of a method, we would generate a fatal error in your application.
72+
code. Regular interfaces, by contrast, may be extended between minor releases,
73+
for example by adding a new method. Be prepared to upgrade your code manually
74+
if you implement a regular interface.
75+
76+
.. note::
77+
78+
Even if we do changes that require manual upgrades, we limit ourselves to
79+
changes that can be upgraded easily. We will always document the precise
80+
upgrade instructions in the UPGRADE file in Symfony's root directory.
7581

7682
The following table explains in detail which use cases are covered by our
7783
backwards compatibility promise:
@@ -89,9 +95,9 @@ backwards compatibility promise:
8995
+-----------------------------------------------+---------------+---------------+
9096
| Implement a method | No [1]_ | Yes |
9197
+-----------------------------------------------+---------------+---------------+
92-
| Add a parameter to an implemented method | No [1]_ | Yes |
98+
| Add an argument to an implemented method | No [1]_ | Yes |
9399
+-----------------------------------------------+---------------+---------------+
94-
| Add a default value to a parameter | Yes | Yes |
100+
| Add a default value to an argument | Yes | Yes |
95101
+-----------------------------------------------+---------------+---------------+
96102

97103
.. include:: _api_tagging.rst.inc
@@ -107,7 +113,7 @@ public methods and properties.
107113
Classes, properties and methods that bear the tag ``@internal`` as well as
108114
the classes located in the various ``*\\Tests\\`` namespaces are an
109115
exception to this rule. They are meant for internal use only and should
110-
*never* be accessed by your own code.
116+
not be accessed by your own code.
111117

112118
Just like with interfaces, we also distinguish between regular and API classes.
113119
Like API interfaces, API classes are marked with an ``@api`` tag::
@@ -127,9 +133,15 @@ Like API interfaces, API classes are marked with an ``@api`` tag::
127133
The difference between regular and API classes is that we guarantee full
128134
backwards compatibility if you extend an API class and override its methods. We
129135
can't give the same promise for regular classes, because there we may, for
130-
example, add an optional parameter to a method. Consequently, the signature of
136+
example, add an optional argument to a method. Consequently, the signature of
131137
your overridden method wouldn't match anymore and generate a fatal error.
132138

139+
.. note::
140+
141+
As with interfaces, we limit ourselves to changes that can be upgraded
142+
easily. We will document the precise ugprade instructions in the UPGRADE
143+
file in Symfony's root directory.
144+
133145
In some cases, only specific properties and methods are tagged with the ``@api``
134146
tag, even though their class is not. In these cases, we guarantee full backwards
135147
compatibility for the tagged properties and methods (as indicated in the column
@@ -171,9 +183,13 @@ covered by our backwards compatibility promise:
171183
+-----------------------------------------------+---------------+---------------+
172184
| Add a new method | No | No |
173185
+-----------------------------------------------+---------------+---------------+
174-
| Add a parameter to an overridden method | No [1]_ | Yes |
186+
| Add an argument to an overridden method | No [1]_ | Yes |
187+
+-----------------------------------------------+---------------+---------------+
188+
| Add a default value to an argument | Yes | Yes |
189+
+-----------------------------------------------+---------------+---------------+
190+
| Call a private method (via Reflection) | No | No |
175191
+-----------------------------------------------+---------------+---------------+
176-
| Add a default value to a parameter | Yes | Yes |
192+
| Access a private property (via Reflection) | No | No |
177193
+-----------------------------------------------+---------------+---------------+
178194

179195
.. include:: _api_tagging.rst.inc
@@ -201,14 +217,14 @@ Remove parent interface No No
201217
Add method Yes [2]_ No
202218
Remove method No No
203219
Change name No No
204-
Add parameter without a default value No No
205-
Add parameter with a default value Yes [2]_ No
206-
Remove parameter Yes [3]_ Yes [3]_
207-
Add default value to a parameter Yes [2]_ No
208-
Remove default value of a parameter No No
209-
Add type hint to a parameter No No
210-
Remove type hint of a parameter Yes [2]_ No
211-
Change parameter type Yes [2]_ [4]_ No
220+
Add argument without a default value No No
221+
Add argument with a default value Yes [2]_ No
222+
Remove argument Yes [3]_ Yes [3]_
223+
Add default value to an argument Yes [2]_ No
224+
Remove default value of an argument No No
225+
Add type hint to an argument No No
226+
Remove type hint of an argument Yes [2]_ No
227+
Change argument type Yes [2]_ [4]_ No
212228
Change return type Yes [2]_ [5]_ No
213229
============================================== ============== ==============
214230

@@ -236,8 +252,11 @@ Reduce visibility No No
236252
Add protected property Yes Yes
237253
Remove protected property Yes [2]_ No
238254
Reduce visibility Yes [2]_ No
255+
**Private Properties**
256+
Add private property Yes Yes
257+
Remove private property Yes Yes
239258
**Constructors**
240-
Add constructor without mandatory parameters Yes [2]_ Yes [2]_
259+
Add constructor without mandatory arguments Yes [2]_ Yes [2]_
241260
Remove constructor Yes [2]_ No
242261
Reduce visibility of a public constructor No No
243262
Reduce visibility of a protected constructor Yes [2]_ No
@@ -246,29 +265,43 @@ Add public method Yes Yes
246265
Remove public method No No
247266
Change name No No
248267
Reduce visibility No No
249-
Add parameter without a default value No No
250-
Add parameter with a default value Yes [2]_ No
251-
Remove parameter Yes [3]_ Yes [3]_
252-
Add default value to a parameter Yes [2]_ No
253-
Remove default value of a parameter No No
254-
Add type hint to a parameter Yes [7]_ No
255-
Remove type hint of a parameter Yes [2]_ No
256-
Change parameter type Yes [2]_ [4]_ No
268+
Add argument without a default value No No
269+
Add argument with a default value Yes [2]_ No
270+
Remove argument Yes [3]_ Yes [3]_
271+
Add default value to an argument Yes [2]_ No
272+
Remove default value of an argument No No
273+
Add type hint to an argument Yes [7]_ No
274+
Remove type hint of an argument Yes [2]_ No
275+
Change argument type Yes [2]_ [4]_ No
257276
Change return type Yes [2]_ [5]_ No
258277
**Protected Methods**
259278
Add protected method Yes Yes
260279
Remove protected method Yes [2]_ No
261280
Change name No No
262281
Reduce visibility Yes [2]_ No
263-
Add parameter without a default value Yes [2]_ No
264-
Add parameter with a default value Yes [2]_ No
265-
Remove parameter Yes [3]_ Yes [3]_
266-
Add default value to a parameter Yes [2]_ No
267-
Remove default value of a parameter Yes [2]_ No
268-
Add type hint to a parameter Yes [2]_ No
269-
Remove type hint of a parameter Yes [2]_ No
270-
Change parameter type Yes [2]_ [4]_ No
282+
Add argument without a default value Yes [2]_ No
283+
Add argument with a default value Yes [2]_ No
284+
Remove argument Yes [3]_ Yes [3]_
285+
Add default value to an argument Yes [2]_ No
286+
Remove default value of an argument Yes [2]_ No
287+
Add type hint to an argument Yes [2]_ No
288+
Remove type hint of an argument Yes [2]_ No
289+
Change argument type Yes [2]_ [4]_ No
271290
Change return type Yes [2]_ [5]_ No
291+
**Private Methods**
292+
Add private method Yes Yes
293+
Remove private method Yes Yes
294+
Change name Yes Yes
295+
Reduce visibility Yes Yes
296+
Add argument without a default value Yes Yes
297+
Add argument with a default value Yes Yes
298+
Remove argument Yes Yes
299+
Add default value to an argument Yes Yes
300+
Remove default value of an argument Yes Yes
301+
Add type hint to an argument Yes Yes
302+
Remove type hint of an argument Yes Yes
303+
Change argument type Yes Yes
304+
Change return type Yes Yes
272305
================================================== ============== ==============
273306

274307
.. [1] Your code may be broken by changes in the Symfony code. Such changes will
@@ -277,9 +310,10 @@ Change return type Yes [2]_ [5]_ No
277310
.. [2] Should be avoided. When done, this change must be documented in the
278311
UPGRADE file.
279312
280-
.. [3] Only the last parameter(s) of a method may be removed.
313+
.. [3] Only the last argument(s) of a method may be removed, as PHP does not
314+
care about additional arguments that you pass to a method.
281315
282-
.. [4] The parameter type may only be changed to a compatible or less specific
316+
.. [4] The argument type may only be changed to a compatible or less specific
283317
type. The following type changes are allowed:
284318
285319
=================== ==================================================================

0 commit comments

Comments
 (0)