Skip to content

Commit 6d9edf1

Browse files
webmozartwebmozart
committed
Improved wording: Changed "safe" to "guaranteed"
1 parent ef1f021 commit 6d9edf1

File tree

1 file changed

+58
-58
lines changed

1 file changed

+58
-58
lines changed

‎contributing/code/bc.rst

+58-58
Original file line numberDiff line numberDiff line change
@@ -32,17 +32,14 @@ Normal Interfaces
3232
All interfaces in the ``Symfony`` namespace are **safe for use**. That means
3333
that:
3434

35-
* You can safely type hint against the interface.
35+
* You can type hint against the interface.
3636

37-
* You can safely call any of the methods provided by the interface.
37+
* You can call any of the methods provided by the interface.
3838

3939
However:
4040

41-
* You cannot safely implement the interface. The interface may change, but all
42-
changes will be documented in the UPGRADE file.
43-
44-
Methods tagged with ``@api`` are treated as if they belonged to an API
45-
interface.
41+
* You cannot implement the interface. The interface may change, but all changes
42+
will be documented in the UPGRADE file.
4643

4744

4845
API Interfaces
@@ -51,7 +48,7 @@ API Interfaces
5148
All interfaces tagged with ``@api`` are also **safe for implementation**. That
5249
means that:
5350

54-
* You can safely implement the interface.
51+
* You can implement the interface.
5552

5653

5754
Internal Interfaces
@@ -68,24 +65,25 @@ Interfaces or interface methods tagged with ``@deprecated`` will be removed in
6865
a future Symfony version. You should never use nor implement them.
6966

7067

71-
Safe Operations
72-
...............
68+
Guarantee Details
69+
.................
7370

74-
The following table summarizes the safe operations when using our interfaces:
71+
When using our interfaces, we guarantee full backwards compatibility for the
72+
following use cases:
7573

7674
============================================== ============== ==============
77-
Operation Normal API
75+
Use Case Normal API
7876
============================================== ============== ==============
79-
Type hint against Safe Safe
80-
Call method Safe Safe
77+
Type hint against Yes Yes
78+
Call method Yes Yes
8179
**In Implementing Classes**
82-
Implement method Not Safe [1]_ Safe
83-
Add custom method Not Safe [1]_ Safe
84-
Add custom method parameter Not Safe [1]_ Safe
85-
Add parameter default value Safe Safe
80+
Implement method No [1]_ Yes
81+
Add custom method No [1]_ Yes
82+
Add custom method parameter No [1]_ Yes
83+
Add parameter default value Yes Yes
8684
============================================== ============== ==============
8785

88-
If you need to do any of the things marked as "Not Safe" above, feel free to
86+
If you need to do any of the things marked with "No" above, feel free to
8987
ask us whether the ``@api`` tag can be added on the respective Symfony code.
9088
For that, simply open a `new ticket on GitHub`_.
9189

@@ -98,27 +96,24 @@ Normal Classes
9896

9997
All classes in the ``Symfony`` namespace are **safe for use**. That means that:
10098

101-
* You can safely type hint against the class' name.
99+
* You can type hint against the class' name.
102100

103-
* You can safely create new instances.
101+
* You can create new instances.
104102

105-
* You can safely extend the class.
103+
* You can extend the class.
106104

107-
* You can safely access public properties.
105+
* You can access public properties.
108106

109-
* You can safely call public methods.
107+
* You can call public methods.
110108

111109
When extending the class:
112110

113-
* You can safely override public properties.
111+
* You can override public properties.
114112

115113
However:
116114

117-
* You cannot safely override methods in extending classes. The class may change,
118-
but all changes will be documented in the UPGRADE file.
119-
120-
Properties and methods tagged with ``@api`` are treated as if they belonged
121-
to an API class.
115+
* You cannot override methods in extending classes. The class may change, but
116+
all changes will be documented in the UPGRADE file.
122117

123118

124119
API Classes
@@ -127,27 +122,31 @@ API Classes
127122
All classes tagged with ``@api`` are also **safe for extension**. That means
128123
that:
129124

130-
* You can safely access protected properties and methods.
125+
* You can access protected properties and methods.
131126

132-
* You can safely call protected methods.
127+
* You can call protected methods.
133128

134-
* You can safely override protected properties.
129+
* You can override protected properties.
135130

136-
* You can safely override public and protected methods.
131+
* You can override public and protected methods.
132+
133+
Properties and methods tagged with ``@api`` are treated as if they belonged
134+
to an API class. That means that you can call or override them regardless of
135+
whether their class has the ``@api`` tag or not.
137136

138137

139138
Internal Classes
140139
................
141140

142-
Classes, properties and class methods tagged with ``@internal`` are meant for
143-
internal use in Symfony only. You should never use nor extend them.
141+
Classes, properties and methods tagged with ``@internal`` are meant for internal
142+
use in Symfony only. You should never use nor extend them.
144143

145144

146145
Deprecated Classes
147146
..................
148147

149-
Classes, properties and class methods tagged with ``@deprecated`` will be
150-
removed in a future Symfony version. You should never use nor extend them.
148+
Classes, properties and methods tagged with ``@deprecated`` will be removed in
149+
a future Symfony version. You should never use nor extend them.
151150

152151

153152
Test Classes
@@ -157,33 +156,34 @@ All classes located in the various ``*\\Tests\\`` namespaces are meant for
157156
internal use only. You should never create, extend or call them directly.
158157

159158

160-
Safe Operations
161-
...............
159+
Guarantee Details
160+
.................
162161

163-
The following table summarizes the safe operations when using our classes:
162+
When using our classes, we guarantee full backwards compatibility for the
163+
following use cases:
164164

165165
============================================== ============== ==============
166-
Operation Normal API
166+
Use Case Normal API
167167
============================================== ============== ==============
168-
Type hint against Safe Safe
169-
Create instance Safe Safe
170-
Extend Safe Safe
171-
Access public property Safe Safe
172-
Call public method Safe Safe
168+
Type hint against Yes Yes
169+
Create instance Yes Yes
170+
Extend Yes Yes
171+
Access public property Yes Yes
172+
Call public method Yes Yes
173173
**In Extending Classes**
174-
Access protected property Not Safe [1]_ Safe
175-
Call protected method Not Safe [1]_ Safe
176-
Override public property Safe Safe
177-
Override protected property Not Safe [1]_ Safe
178-
Override public method Not Safe [1]_ Safe
179-
Override protected method Not Safe [1]_ Safe
180-
Add custom property Not Safe Not Safe
181-
Add custom method Not Safe Not Safe
182-
Add custom method parameter Not Safe [1]_ Safe
183-
Add parameter default value Safe Safe
174+
Access protected property No [1]_ Yes
175+
Call protected method No [1]_ Yes
176+
Override public property Yes Yes
177+
Override protected property No [1]_ Yes
178+
Override public method No [1]_ Yes
179+
Override protected method No [1]_ Yes
180+
Add custom property No No
181+
Add custom method No No
182+
Add custom method parameter No [1]_ Yes
183+
Add parameter default value Yes Yes
184184
============================================== ============== ==============
185185

186-
If you need to do any of the things marked as "Not Safe" above, feel free to
186+
If you need to do any of the things marked with "No" above, feel free to
187187
ask us whether the ``@api`` tag can be added on the respective Symfony code.
188188
For that, simply open a `new ticket on GitHub`_.
189189

0 commit comments

Comments
 (0)