Skip to content

Commit 9af74fe

Browse files
authored
[docs] LibraryEvolution: Feedback from DaveA and co. (#5066)
- Clear up allowed changes for associated types. - Modifying a fixed_contents struct's properties' accessors isn't inherently ABI-breaking, just behavior-changing like any other inlineable thing. - Clarify what an "empty extension" is.
1 parent a05e841 commit 9af74fe

File tree

1 file changed

+13
-4
lines changed

1 file changed

+13
-4
lines changed

docs/LibraryEvolution.rst

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -735,8 +735,9 @@ properties in a ``@fixedContents`` struct are implicitly declared
735735
vice versa.
736736
- Changing the body of any *existing* methods, initializers, computed property
737737
accessors, or non-instance stored property accessors is permitted. Changing
738-
the body of a stored instance property observing accessor is only permitted
739-
if the property is not `versioned <versioned entity>`.
738+
the body of a stored instance property observing accessor is permitted if the
739+
property is not `versioned <versioned entity>`, and considered a
740+
`binary-compatible source-breaking change` if it is.
740741
- Adding or removing observing accessors from any
741742
`versioned <versioned entity>` stored instance properties (public or
742743
non-public) is not permitted.
@@ -903,11 +904,14 @@ not handle new cases well.
903904
Protocols
904905
~~~~~~~~~
905906

906-
There are very few safe changes to make to protocols:
907+
There are very few safe changes to make to protocols and their members:
907908

908909
- A new non-type requirement may be added to a protocol, as long as it has an
909910
unconstrained default implementation.
910911
- A new associated type may be added to a protocol, as long as it has a default.
912+
As with any other declarations, newly-added associated types must be marked
913+
with ``@available`` specifying when they were introduced.
914+
- A default may be added to an associated type.
911915
- A new optional requirement may be added to an ``@objc`` protocol.
912916
- All members may be reordered, including associated types.
913917
- Changing *internal* parameter names of function and subscript requirements
@@ -922,6 +926,8 @@ All other changes to the protocol itself are forbidden, including:
922926

923927
- Making an existing requirement optional.
924928
- Making a non-``@objc`` protocol ``@objc`` or vice versa.
929+
- Adding or removing constraints from an associated type.
930+
- Removing a default from an associated type.
925931

926932
Protocol extensions may be more freely modified; `see below`__.
927933

@@ -1162,14 +1168,17 @@ Extensions
11621168
Non-protocol extensions largely follow the same rules as the types they extend.
11631169
The following changes are permitted:
11641170

1165-
- Adding new extensions and removing empty extensions.
1171+
- Adding new extensions and removing empty extensions (that is, extensions that
1172+
declare neither members nor protocol conformances).
11661173
- Moving a member from one extension to another within the same module, as long
11671174
as both extensions have the exact same constraints.
11681175
- Moving a member from an unconstrained extension to the declaration of the
11691176
base type, provided that the declaration is in the same module. The reverse
11701177
is permitted for all members except stored properties, although note that
11711178
moving all initializers out of a type declaration may cause a new one to be
11721179
implicitly synthesized.
1180+
- Adding a new protocol conformance (with proper availability annotations).
1181+
- Removing conformances to non-public protocols.
11731182

11741183
Adding, removing, reordering, and modifying members follow the same rules as
11751184
the base type; see the sections on structs, enums, and classes above.

0 commit comments

Comments
 (0)