Skip to content

Commit 28c90ab

Browse files
committed
Another round of updates for LibaryEvolution.rst
Adding new protocol requirements is now a "binary compatible source breaking change" without explicit guarantees about source compatibility. Removing a default from an associated type is not binary compatible because the associated type may itself have been added resiliently, in which case clients that predate the associated type will not be able to instantiate a witness table for the protocol.
1 parent 80419c7 commit 28c90ab

File tree

1 file changed

+14
-26
lines changed

1 file changed

+14
-26
lines changed

docs/LibraryEvolution.rst

Lines changed: 14 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -837,12 +837,7 @@ Protocols
837837

838838
There are very few safe changes to make to protocols and their members:
839839

840-
- A new non-type requirement may be added to a protocol, as long as it has an
841-
unconstrained default implementation.
842-
- A new associated type requirement may be added as long as it has a default.
843840
- A default may be added to an associated type.
844-
- Removing a default from an associated type is a `binary-compatible
845-
source-breaking change`.
846841
- A new optional requirement may be added to an ``@objc`` protocol.
847842
- All members may be reordered, including associated types.
848843
- Changing *internal* parameter names of function and subscript requirements
@@ -853,40 +848,33 @@ There are very few safe changes to make to protocols and their members:
853848
be added to a function requirement without any additional versioning
854849
information.
855850

856-
Note that clients can use a protocol as an existential type as long as it does
857-
not have any associated types or requirements containing ``Self`` in
858-
non-covariant position. Therefore adding such a requirement becomes a
859-
`binary-compatible source-breaking change`.
851+
New requirements can be added to a protocol. However, restrictions around
852+
existential types mean that adding new associated types or non-type requirements
853+
involving ``Self`` can break source compatibility. For this reason, the following
854+
are `binary-compatible source-breaking changes`:
860855

861-
Adding such requirements to protocols that already contain such requirements and
862-
cannot be used as existential types, on the other hand, is always
863-
source-compatible.
856+
- A new non-type requirement may be added to a protocol, as long as it has an
857+
unconstrained default implementation in a protocol extension of the
858+
protocol itself or some other protocol it refines.
859+
- A new associated type requirement may be added as long as it has a
860+
default.
864861

865862
All other changes to the protocol itself are forbidden, including:
866863

867864
- Adding or removing refined protocols.
868865
- Removing any existing requirements (type or non-type).
866+
- Removing the default type of an associated type.
869867
- Making an existing requirement optional.
870868
- Making a non-``@objc`` protocol ``@objc`` or vice versa.
871-
- Adding or removing constraints from an associated type, including inherited
872-
associated types.
869+
- Adding or removing protocols and superclasses from the inheritance
870+
clause of an associated type.
871+
- Adding or removing constraints from the ``where`` clause of
872+
the protocol or an associated type.
873873

874874
Protocol extensions may be more freely modified; `see below`__.
875875

876876
__ #protocol-extensions
877877

878-
.. note::
879-
880-
A protocol's associated types are used in computing the "generic signature"
881-
that uniquely identifies a generic function. Adding an associated type
882-
could perturb the generic signature and thus change the identity of a
883-
function, breaking binary compatibility.
884-
885-
It may be possible to allow adding associated types as long as they have
886-
proper availability annotations, but this is not in scope for the initial
887-
version of Swift ABI stability.
888-
889-
890878
Classes
891879
~~~~~~~
892880

0 commit comments

Comments
 (0)