Skip to content

Commit ce58ee9

Browse files
webmozartwebmozart
committed
Added rules for adding parent interfaces and moving methods/properties to parent interfaces/classes
1 parent be2251c commit ce58ee9

File tree

1 file changed

+27
-18
lines changed

1 file changed

+27
-18
lines changed

‎contributing/code/bc.rst

+27-18
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Our Backwards Compatibility Promise
44
Ensuring smooth upgrades of your projects is our first priority. That's why
55
we promise you backwards compatibility (BC) for all minor Symfony releases.
66

7-
You probably recognize this strategy as `Semantic Versioning`_. In short,
7+
You probably recognize this strategy as `Semantic Versioning`_. In short,
88
Semantic Versioning means that only major releases (such as 2.0, 3.0 etc.) are
99
allowed to break backwards compatibility. Minor releases (such as 2.5, 2.6 etc.)
1010
may introduce new features, but must do so without breaking the existing API of
@@ -211,21 +211,22 @@ Type of Change Regular API
211211
============================================== ============== ==============
212212
Remove entirely No No
213213
Change name or namespace No No
214-
Add parent interface Yes [2]_ No
214+
Add parent interface Yes [2]_ Yes [3]_
215215
Remove parent interface No No
216216
**Methods**
217217
Add method Yes [2]_ No
218218
Remove method No No
219219
Change name No No
220+
Move to parent interface Yes Yes
220221
Add argument without a default value No No
221222
Add argument with a default value Yes [2]_ No
222-
Remove argument Yes [3]_ Yes [3]_
223+
Remove argument Yes [4]_ Yes [4]_
223224
Add default value to an argument Yes [2]_ No
224225
Remove default value of an argument No No
225226
Add type hint to an argument No No
226227
Remove type hint of an argument Yes [2]_ No
227-
Change argument type Yes [2]_ [4]_ No
228-
Change return type Yes [2]_ [5]_ No
228+
Change argument type Yes [2]_ [5]_ No
229+
Change return type Yes [2]_ [6]_ No
229230
============================================== ============== ==============
230231

231232
Changing Classes
@@ -241,17 +242,19 @@ Remove entirely No No
241242
Make final Yes [2]_ No
242243
Make abstract No No
243244
Change name or namespace No No
244-
Change parent class Yes [6]_ Yes [6]_
245+
Change parent class Yes [7]_ Yes [7]_
245246
Add interface Yes Yes
246247
Remove interface No No
247248
**Public Properties**
248249
Add public property Yes Yes
249250
Remove public property No No
250251
Reduce visibility No No
252+
Move to parent class Yes Yes
251253
**Protected Properties**
252254
Add protected property Yes Yes
253255
Remove protected property Yes [2]_ No
254256
Reduce visibility Yes [2]_ No
257+
Move to parent class Yes Yes
255258
**Private Properties**
256259
Add private property Yes Yes
257260
Remove private property Yes Yes
@@ -260,34 +263,37 @@ Add constructor without mandatory arguments Yes [2]_ Yes [2]_
260263
Remove constructor Yes [2]_ No
261264
Reduce visibility of a public constructor No No
262265
Reduce visibility of a protected constructor Yes [2]_ No
266+
Move to parent class Yes Yes
263267
**Public Methods**
264268
Add public method Yes Yes
265269
Remove public method No No
266270
Change name No No
267271
Reduce visibility No No
272+
Move to parent class Yes Yes
268273
Add argument without a default value No No
269274
Add argument with a default value Yes [2]_ No
270-
Remove argument Yes [3]_ Yes [3]_
275+
Remove argument Yes [4]_ Yes [4]_
271276
Add default value to an argument Yes [2]_ No
272277
Remove default value of an argument No No
273-
Add type hint to an argument Yes [7]_ No
278+
Add type hint to an argument Yes [8]_ No
274279
Remove type hint of an argument Yes [2]_ No
275-
Change argument type Yes [2]_ [4]_ No
276-
Change return type Yes [2]_ [5]_ No
280+
Change argument type Yes [2]_ [5]_ No
281+
Change return type Yes [2]_ [6]_ No
277282
**Protected Methods**
278283
Add protected method Yes Yes
279284
Remove protected method Yes [2]_ No
280285
Change name No No
281286
Reduce visibility Yes [2]_ No
287+
Move to parent class Yes Yes
282288
Add argument without a default value Yes [2]_ No
283289
Add argument with a default value Yes [2]_ No
284-
Remove argument Yes [3]_ Yes [3]_
290+
Remove argument Yes [4]_ Yes [4]_
285291
Add default value to an argument Yes [2]_ No
286292
Remove default value of an argument Yes [2]_ No
287293
Add type hint to an argument Yes [2]_ No
288294
Remove type hint of an argument Yes [2]_ No
289-
Change argument type Yes [2]_ [4]_ No
290-
Change return type Yes [2]_ [5]_ No
295+
Change argument type Yes [2]_ [5]_ No
296+
Change return type Yes [2]_ [6]_ No
291297
**Private Methods**
292298
Add private method Yes Yes
293299
Remove private method Yes Yes
@@ -310,10 +316,13 @@ Change return type Yes Yes
310316
.. [2] Should be avoided. When done, this change must be documented in the
311317
UPGRADE file.
312318
313-
.. [3] Only the last argument(s) of a method may be removed, as PHP does not
319+
.. [3] The added parent interface must not introduce any new methods that don't
320+
exist in the interface already.
321+
322+
.. [4] Only the last argument(s) of a method may be removed, as PHP does not
314323
care about additional arguments that you pass to a method.
315324
316-
.. [4] The argument type may only be changed to a compatible or less specific
325+
.. [5] The argument type may only be changed to a compatible or less specific
317326
type. The following type changes are allowed:
318327
319328
=================== ==================================================================
@@ -327,7 +336,7 @@ Change return type Yes Yes
327336
interface ``<I>`` any superinterface of ``<I>``
328337
=================== ==================================================================
329338
330-
.. [5] The return type may only be changed to a compatible or more specific
339+
.. [6] The return type may only be changed to a compatible or more specific
331340
type. The following type changes are allowed:
332341
333342
=================== ==================================================================
@@ -345,10 +354,10 @@ Change return type Yes Yes
345354
interface ``<I>`` any subinterface or implementing class of ``<I>``
346355
=================== ==================================================================
347356
348-
.. [6] When changing the parent class, the original parent class must remain an
357+
.. [7] When changing the parent class, the original parent class must remain an
349358
ancestor of the class.
350359
351-
.. [7] A type hint may only be added if passing a value with a different type
360+
.. [8] A type hint may only be added if passing a value with a different type
352361
previously generated a fatal error.
353362
354363
.. _Semantic Versioning: http://semver.org/

0 commit comments

Comments
 (0)