Skip to content

[docs] LibraryEvolution: Feedback from DaveA and co. #5066

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 5, 2016
Merged

[docs] LibraryEvolution: Feedback from DaveA and co. #5066

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions docs/LibraryEvolution.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -735,8 +735,9 @@ properties in a ``@fixedContents`` struct are implicitly declared
vice versa.
- Changing the body of any *existing* methods, initializers, computed property
accessors, or non-instance stored property accessors is permitted. Changing
the body of a stored instance property observing accessor is only permitted
if the property is not `versioned <versioned entity>`.
the body of a stored instance property observing accessor is permitted if the
property is not `versioned <versioned entity>`, and considered a
`binary-compatible source-breaking change` if it is.
- Adding or removing observing accessors from any
`versioned <versioned entity>` stored instance properties (public or
non-public) is not permitted.
Expand Down Expand Up @@ -903,11 +904,14 @@ not handle new cases well.
Protocols
~~~~~~~~~

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

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

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

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

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

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

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