@@ -75,7 +75,7 @@ backward compatibility promise:
7575+-----------------------------------------------+-----------------------------+
7676| Type hint against the interface | Yes |
7777+-----------------------------------------------+-----------------------------+
78- | Call a method | Yes [10 ]_ |
78+ | Call a method | Yes :ref: ` [10] < note-10 >` |
7979+-----------------------------------------------+-----------------------------+
8080| **If you implement the interface and... ** | **Then we guarantee BC... ** |
8181+-----------------------------------------------+-----------------------------+
@@ -117,13 +117,13 @@ covered by our backward compatibility promise:
117117+-----------------------------------------------+-----------------------------+
118118| Access a public property | Yes |
119119+-----------------------------------------------+-----------------------------+
120- | Call a public method | Yes [10 ]_ |
120+ | Call a public method | Yes :ref: ` [10] < note-10 >` |
121121+-----------------------------------------------+-----------------------------+
122122| **If you extend the class and... ** | **Then we guarantee BC... ** |
123123+-----------------------------------------------+-----------------------------+
124124| Access a protected property | Yes |
125125+-----------------------------------------------+-----------------------------+
126- | Call a protected method | Yes [10 ]_ |
126+ | Call a protected method | Yes :ref: ` [10] < note-10 >` |
127127+-----------------------------------------------+-----------------------------+
128128| Override a public property | Yes |
129129+-----------------------------------------------+-----------------------------+
@@ -193,12 +193,12 @@ Changing Interfaces
193193This table tells you which changes you are allowed to do when working on
194194Symfony's interfaces:
195195
196- ============================================== ==============
197- Type of Change Change Allowed
198- ============================================== ==============
196+ ============================================== ============== ===============
197+ Type of Change Change Allowed Notes
198+ ============================================== ============== ===============
199199Remove entirely No
200200Change name or namespace No
201- Add parent interface Yes [2 ]_
201+ Add parent interface Yes :ref: ` [2] < note-2 >`
202202Remove parent interface No
203203**Methods **
204204Add method No
@@ -207,38 +207,38 @@ Change name No
207207Move to parent interface Yes
208208Add argument without a default value No
209209Add argument with a default value No
210- Remove argument No [3 ]_
210+ Remove argument No :ref: ` [3] < note-3 >`
211211Add default value to an argument No
212212Remove default value of an argument No
213213Add type hint to an argument No
214214Remove type hint of an argument No
215215Change argument type No
216216Add return type No
217- Remove return type No [9 ]_
217+ Remove return type No :ref: ` [9] < note-9 >`
218218Change return type No
219219**Static Methods **
220220Turn non static into static No
221221Turn static into non static No
222222**Constants **
223223Add constant Yes
224224Remove constant No
225- Change value of a constant Yes [1 ]_ [5 ]_
226- ============================================== ==============
225+ Change value of a constant Yes :ref: ` [1] < note-1 >` :ref: ` [5] < note-5 >`
226+ ============================================== ============== ===============
227227
228228Changing Classes
229229~~~~~~~~~~~~~~~~
230230
231231This table tells you which changes you are allowed to do when working on
232232Symfony's classes:
233233
234- ================================================== ==============
235- Type of Change Change Allowed
236- ================================================== ==============
234+ ================================================== ============== ===============
235+ Type of Change Change Allowed Notes
236+ ================================================== ============== ===============
237237Remove entirely No
238- Make final No [6 ]_
238+ Make final No :ref: ` [6] < note-6 >`
239239Make abstract No
240240Change name or namespace No
241- Change parent class Yes [4 ]_
241+ Change parent class Yes :ref: ` [4] < note-4 >`
242242Add interface Yes
243243Remove interface No
244244**Public Properties **
@@ -248,19 +248,19 @@ Reduce visibility No
248248Move to parent class Yes
249249**Protected Properties **
250250Add protected property Yes
251- Remove protected property No [7 ]_
252- Reduce visibility No [7 ]_
253- Make public No [7 ]_
251+ Remove protected property No :ref: ` [7] < note-7 >`
252+ Reduce visibility No :ref: ` [7] < note-7 >`
253+ Make public No :ref: ` [7] < note-7 >`
254254Move to parent class Yes
255255**Private Properties **
256256Add private property Yes
257257Make public or protected Yes
258258Remove private property Yes
259259**Constructors **
260- Add constructor without mandatory arguments Yes [1 ]_
260+ Add constructor without mandatory arguments Yes :ref: ` [1] < note-1 >`
261261Remove constructor No
262262Reduce visibility of a public constructor No
263- Reduce visibility of a protected constructor No [7 ]_
263+ Reduce visibility of a protected constructor No :ref: ` [7] < note-7 >`
264264Move to parent class Yes
265265**Destructors **
266266Add destructor Yes
@@ -271,38 +271,38 @@ Add public method Yes
271271Remove public method No
272272Change name No
273273Reduce visibility No
274- Make final No [6 ]_
274+ Make final No :ref: ` [6] < note-6 >`
275275Move to parent class Yes
276276Add argument without a default value No
277- Add argument with a default value No [7 ]_ [8 ]_
278- Remove argument No [3 ]_
279- Add default value to an argument No [7 ]_ [8 ]_
277+ Add argument with a default value No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
278+ Remove argument No :ref: ` [3] < note-3 >`
279+ Add default value to an argument No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
280280Remove default value of an argument No
281- Add type hint to an argument No [7 ]_ [8 ]_
282- Remove type hint of an argument No [7 ]_ [8 ]_
283- Change argument type No [7 ]_ [8 ]_
284- Add return type No [7 ]_ [8 ]_
285- Remove return type No [7 ]_ [8 ]_ [9 ]_
286- Change return type No [7 ]_ [8 ]_
281+ Add type hint to an argument No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
282+ Remove type hint of an argument No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
283+ Change argument type No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
284+ Add return type No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
285+ Remove return type No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >` :ref: ` [9] < note-9 >`
286+ Change return type No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
287287**Protected Methods **
288288Add protected method Yes
289- Remove protected method No [7 ]_
290- Change name No [7 ]_
291- Reduce visibility No [7 ]_
292- Make final No [6 ]_
293- Make public No [7 ]_ [8 ]_
289+ Remove protected method No :ref: ` [7] < note-7 >`
290+ Change name No :ref: ` [7] < note-7 >`
291+ Reduce visibility No :ref: ` [7] < note-7 >`
292+ Make final No :ref: ` [6] < note-6 >`
293+ Make public No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
294294Move to parent class Yes
295- Add argument without a default value No [7 ]_
296- Add argument with a default value No [7 ]_ [8 ]_
297- Remove argument No [3 ]_
298- Add default value to an argument No [7 ]_ [8 ]_
299- Remove default value of an argument No [7 ]_
300- Add type hint to an argument No [7 ]_ [8 ]_
301- Remove type hint of an argument No [7 ]_ [8 ]_
302- Change argument type No [7 ]_ [8 ]_
303- Add return type No [7 ]_ [8 ]_
304- Remove return type No [7 ]_ [8 ]_ [9 ]_
305- Change return type No [7 ]_ [8 ]_
295+ Add argument without a default value No :ref: ` [7] < note-7 >`
296+ Add argument with a default value No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
297+ Remove argument No :ref: ` [3] < note-3 >`
298+ Add default value to an argument No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
299+ Remove default value of an argument No :ref: ` [7] < note-7 >`
300+ Add type hint to an argument No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
301+ Remove type hint of an argument No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
302+ Change argument type No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
303+ Add return type No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
304+ Remove return type No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >` :ref: ` [9] < note-9 >`
305+ Change return type No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
306306**Private Methods **
307307Add private method Yes
308308Remove private method Yes
@@ -320,23 +320,23 @@ Add return type Yes
320320Remove return type Yes
321321Change return type Yes
322322**Static Methods and Properties **
323- Turn non static into static No [7 ]_ [8 ]_
323+ Turn non static into static No :ref: ` [7] < note-7 >` :ref: ` [8] < note-8 >`
324324Turn static into non static No
325325**Constants **
326326Add constant Yes
327327Remove constant No
328- Change value of a constant Yes [1 ]_ [5 ]_
329- ================================================== ==============
328+ Change value of a constant Yes :ref: ` [1] < note-1 >` :ref: ` [5] < note-5 >`
329+ ================================================== ============== ===============
330330
331331Changing Traits
332332~~~~~~~~~~~~~~~
333333
334334This table tells you which changes you are allowed to do when working on
335335Symfony's traits:
336336
337- ================================================== ==============
338- Type of Change Change Allowed
339- ================================================== ==============
337+ ================================================== ============== ===============
338+ Type of Change Change Allowed Notes
339+ ================================================== ============== ===============
340340Remove entirely No
341341Change name or namespace No
342342Use another trait Yes
@@ -363,7 +363,7 @@ Add public method Yes
363363Remove public method No
364364Change name No
365365Reduce visibility No
366- Make final No [6 ]_
366+ Make final No :ref: ` [6] < note-6 >`
367367Move to used trait Yes
368368Add argument without a default value No
369369Add argument with a default value No
@@ -379,8 +379,8 @@ Add protected method Yes
379379Remove protected method No
380380Change name No
381381Reduce visibility No
382- Make final No [6 ]_
383- Make public No [8 ]_
382+ Make final No :ref: ` [6] < note-6 >`
383+ Make public No :ref: ` [8] < note-8 >`
384384Move to used trait Yes
385385Add argument without a default value No
386386Add argument with a default value No
@@ -411,45 +411,66 @@ Change return type No
411411**Static Methods and Properties **
412412Turn non static into static No
413413Turn static into non static No
414- ================================================== ==============
414+ ================================================== ============== ===============
415415
416- .. [ 1 ] Should be avoided. When done, this change must be documented in the
417- UPGRADE file.
416+ Notes
417+ ~~~~~
418418
419- 2 ] The added parent interface must not introduce any new methods that don't
420- exist in the interface already.
419+ .. _note-1 :
421420
422- .. [ 3 ] Only the last optional argument(s) of a method may be removed, as PHP
423- does not care about additional arguments that you pass to a method .
421+ ** [1] ** Should be avoided. When done, this change must be documented in the
422+ UPGRADE file .
424423
425- 4 ] When changing the parent class, the original parent class must remain an
426- ancestor of the class.
424+ .. _note-2 :
427425
428- 5 ] The value of a constant may only be changed when the constants aren't
429- used in configuration (e.g. Yaml and XML files), as these do not support
430- constants and have to hardcode the value. For instance, event name
431- constants can't change the value without introducing a BC break.
432- Additionally, if a constant will likely be used in objects that are
433- serialized, the value of a constant should not be changed.
426+ **[2] ** The added parent interface must not introduce any new methods that don't
427+ exist in the interface already.
434428
435- [ 6 ] Allowed using the `` @final `` annotation.
429+ .. _ note-3 :
436430
437- 7 ] Allowed if the class is final. Classes that received the ``@final ``
438- annotation after their first release are considered final in their
439- next major version.
440- Changing an argument type is only possible with a parent type.
441- Changing a return type is only possible with a child type.
431+ **[3] ** Only the last optional argument(s) of a method may be removed, as PHP
432+ does not care about additional arguments that you pass to a method.
442433
443- 8 ] Allowed if the method is final. Methods that received the ``@final ``
444- annotation after their first release are considered final in their
445- next major version.
446- Changing an argument type is only possible with a parent type.
447- Changing a return type is only possible with a child type.
434+ .. _note-4 :
448435
449- 9 ] Allowed for the ``void `` return type.
436+ **[4] ** When changing the parent class, the original parent class must remain an
437+ ancestor of the class.
450438
451- 10 ] Parameter names are only covered by the compatibility promise for
452- constructors of Attribute classes. Using PHP named arguments might
453- break your code when upgrading to newer Symfony versions.
439+ .. _note-5 :
440+
441+ **[5] ** The value of a constant may only be changed when the constants aren't
442+ used in configuration (e.g. Yaml and XML files), as these do not support
443+ constants and have to hardcode the value. For instance, event name constants
444+ can't change the value without introducing a BC break. Additionally, if a
445+ constant will likely be used in objects that are serialized, the value of a
446+ constant should not be changed.
447+
448+ .. _note-6 :
449+
450+ **[6] ** Allowed using the ``@final `` annotation.
451+
452+ .. _note-7 :
453+
454+ **[7] ** Allowed if the class is final. Classes that received the ``@final ``
455+ annotation after their first release are considered final in their next major
456+ version. Changing an argument type is only possible with a parent type. Changing
457+ a return type is only possible with a child type.
458+
459+ .. _note-8 :
460+
461+ **[8] ** Allowed if the method is final. Methods that received the ``@final ``
462+ annotation after their first release are considered final in their next major
463+ version. Changing an argument type is only possible with a parent type. Changing
464+ a return type is only possible with a child type.
465+
466+ .. _note-9 :
467+
468+ **[9] ** Allowed for the ``void `` return type.
469+
470+ .. _note-10 :
471+
472+ **[10] ** Parameter names are only covered by the compatibility promise for
473+ constructors of Attribute classes. Using PHP named arguments might break your
474+ code when upgrading to newer Symfony versions.
454475
455476.. _`Semantic Versioning` : https://semver.org/
0 commit comments