Skip to content

Commit 23b5b8d

Browse files
javiereguiluzjaviereguiluz
committed
minor #9718 Add traits to BC policy (nicolas-grekas)
This PR was submitted for the 2.7 branch but it was merged into the 2.8 branch instead (closes #9718). Discussion ---------- Add traits to BC policy Changing traits is more constrained that changing classes. Also embeds some things I found missing in other parts. Commits ------- 3c814db Add traits to BC policy
2 parents 551a19b + 3c814db commit 23b5b8d

File tree

1 file changed

+134
-1
lines changed

1 file changed

+134
-1
lines changed

‎contributing/code/bc.rst

+134-1
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,41 @@ covered by our backward compatibility promise:
134134
| Access a private property (via Reflection) | No |
135135
+-----------------------------------------------+-----------------------------+
136136

137+
Using our Traits
138+
~~~~~~~~~~~~~~~~
139+
140+
All traits provided by Symfony may be used in your classes.
141+
142+
.. caution::
143+
144+
The exception to this rule are traits tagged with ``@internal``. Such
145+
traits should not be used.
146+
147+
To be on the safe side, check the following table to know which use cases are
148+
covered by our backward compatibility promise:
149+
150+
+-----------------------------------------------+-----------------------------+
151+
| Use Case | Backward Compatibility |
152+
+===============================================+=============================+
153+
| **If you...** | **Then we guarantee BC...** |
154+
+-----------------------------------------------+-----------------------------+
155+
| Use a trait | Yes |
156+
+-----------------------------------------------+-----------------------------+
157+
| **If you use the trait and...** | **Then we guarantee BC...** |
158+
+-----------------------------------------------+-----------------------------+
159+
| Use it to implement an interface | Yes |
160+
+-----------------------------------------------+-----------------------------+
161+
| Use it to implement an abstract method | Yes |
162+
+-----------------------------------------------+-----------------------------+
163+
| Use it to extend a parent class | Yes |
164+
+-----------------------------------------------+-----------------------------+
165+
| Use it to define an abstract class | Yes |
166+
+-----------------------------------------------+-----------------------------+
167+
| Use a public, protected or private property | Yes |
168+
+-----------------------------------------------+-----------------------------+
169+
| Use a public, protected or private method | Yes |
170+
+-----------------------------------------------+-----------------------------+
171+
137172
Working on Symfony Code
138173
-----------------------
139174

@@ -169,6 +204,9 @@ Change argument type No
169204
Add return type No
170205
Remove return type No [9]_
171206
Change return type No
207+
**Static Methods**
208+
Turn non static into static No
209+
Turn static into non static No
172210
**Constants**
173211
Add constant Yes
174212
Remove constant No
@@ -200,21 +238,28 @@ Move to parent class Yes
200238
Add protected property Yes
201239
Remove protected property No [7]_
202240
Reduce visibility No [7]_
241+
Make public No [7]_
203242
Move to parent class Yes
204243
**Private Properties**
205244
Add private property Yes
245+
Make public or protected Yes
206246
Remove private property Yes
207247
**Constructors**
208248
Add constructor without mandatory arguments Yes [1]_
209249
Remove constructor No
210250
Reduce visibility of a public constructor No
211251
Reduce visibility of a protected constructor No [7]_
212252
Move to parent class Yes
253+
**Destructors**
254+
Add destructor Yes
255+
Remove destructor No
256+
Move to parent class Yes
213257
**Public Methods**
214258
Add public method Yes
215259
Remove public method No
216260
Change name No
217261
Reduce visibility No
262+
Make final No [6]_
218263
Move to parent class Yes
219264
Add argument without a default value No
220265
Add argument with a default value No [7]_ [8]_
@@ -232,6 +277,8 @@ Add protected method Yes
232277
Remove protected method No [7]_
233278
Change name No [7]_
234279
Reduce visibility No [7]_
280+
Make final No [6]_
281+
Make public No [7]_ [8]_
235282
Move to parent class Yes
236283
Add argument without a default value No [7]_
237284
Add argument with a default value No [7]_ [8]_
@@ -248,6 +295,7 @@ Change return type No [7]_ [8]_
248295
Add private method Yes
249296
Remove private method Yes
250297
Change name Yes
298+
Make public or protected Yes
251299
Add argument without a default value Yes
252300
Add argument with a default value Yes
253301
Remove argument Yes
@@ -259,7 +307,7 @@ Change argument type Yes
259307
Add return type Yes
260308
Remove return type Yes
261309
Change return type Yes
262-
**Static Methods**
310+
**Static Methods and Properties**
263311
Turn non static into static No [7]_ [8]_
264312
Turn static into non static No
265313
**Constants**
@@ -268,6 +316,91 @@ Remove constant No
268316
Change value of a constant Yes [1]_ [5]_
269317
================================================== ==============
270318

319+
Changing Traits
320+
~~~~~~~~~~~~~~~
321+
322+
This table tells you which changes you are allowed to do when working on
323+
Symfony's traits:
324+
325+
================================================== ==============
326+
Type of Change Change Allowed
327+
================================================== ==============
328+
Remove entirely No
329+
Change name or namespace No
330+
Use another trait Yes
331+
**Public Properties**
332+
Add public property Yes
333+
Remove public property No
334+
Reduce visibility No
335+
Move to a used trait Yes
336+
**Protected Properties**
337+
Add protected property Yes
338+
Remove protected property No
339+
Reduce visibility No
340+
Make public No
341+
Move to a used trait Yes
342+
**Private Properties**
343+
Add private property Yes
344+
Remove private property No
345+
Make public or protected Yes
346+
Move to a used trait Yes
347+
**Constructors and destructors**
348+
Have constructor or destructor No
349+
**Public Methods**
350+
Add public method Yes
351+
Remove public method No
352+
Change name No
353+
Reduce visibility No
354+
Make final No [6]_
355+
Move to used trait Yes
356+
Add argument without a default value No
357+
Add argument with a default value No
358+
Remove argument No
359+
Add default value to an argument No
360+
Remove default value of an argument No
361+
Add type hint to an argument No
362+
Remove type hint of an argument No
363+
Change argument type No
364+
Change return type No
365+
**Protected Methods**
366+
Add protected method Yes
367+
Remove protected method No
368+
Change name No
369+
Reduce visibility No
370+
Make final No [6]_
371+
Make public No [8]_
372+
Move to used trait Yes
373+
Add argument without a default value No
374+
Add argument with a default value No
375+
Remove argument No
376+
Add default value to an argument No
377+
Remove default value of an argument No
378+
Add type hint to an argument No
379+
Remove type hint of an argument No
380+
Change argument type No
381+
Change return type No
382+
**Private Methods**
383+
Add private method Yes
384+
Remove private method No
385+
Change name No
386+
Make public or protected Yes
387+
Move to used trait Yes
388+
Add argument without a default value No
389+
Add argument with a default value No
390+
Remove argument No
391+
Add default value to an argument No
392+
Remove default value of an argument No
393+
Add type hint to an argument No
394+
Remove type hint of an argument No
395+
Change argument type No
396+
Add return type No
397+
Remove return type No
398+
Change return type No
399+
**Static Methods and Properties**
400+
Turn non static into static No
401+
Turn static into non static No
402+
================================================== ==============
403+
271404
.. [1] Should be avoided. When done, this change must be documented in the
272405
UPGRADE file.
273406

0 commit comments

Comments
 (0)