Skip to content

Minor updates for LibraryEvolution.rst #20135

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 30, 2018
Merged

Minor updates for LibraryEvolution.rst #20135

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
67 changes: 40 additions & 27 deletions docs/LibraryEvolution.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -395,7 +395,7 @@ polar representation::
and the ``x`` and ``y`` properties have now disappeared. To avoid this, the
bodies of inlinable functions have the following restrictions:

- They may not define any local types (other than typealiases).
- They may not define any local types.

- They must not reference any ``private`` or ``fileprivate`` entities.

Expand All @@ -415,12 +415,12 @@ Default argument expressions for functions that are public, versioned, or
inlinable are implemented very similar to inlinable functions and thus are
subject to similar restrictions:

- They may not define any local types (other than typealiases).
- They may not define any local types.

- They must not reference any non-``public`` entities.

- They must not reference any entities from the current module introduced
after the function was made inlinable, except under appropriate availability
after the default argument was added, except under appropriate availability
guards.

A default argument implicitly has the same availability as the function it is
Expand All @@ -438,6 +438,8 @@ changes are permitted:
- Adding or removing a non-public, non-versioned setter.
- Changing from a stored variable to a computed variable, or vice versa, as
long as a previously versioned setter is not removed.
- As a special case of the above, adding or removing ``lazy`` from a stored
property.
- Changing the body of an accessor.
- Adding or removing an observing accessor (``willSet`` or ``didSet``) to/from
an existing variable. This is effectively the same as modifying the body of a
Expand Down Expand Up @@ -482,6 +484,7 @@ amount:
- Adding or removing a non-public, non-versioned setter is still permitted.
- Changing from stored to computed or vice versa is forbidden, because it would
break existing clients.
- Similarly, adding or removing ``lazy`` is forbidden.
- Changing the body of an accessor is a `binary-compatible source-breaking
change`.
- Adding/removing observing accessors is likewise a `binary-compatible
Expand Down Expand Up @@ -530,6 +533,8 @@ the following changes are permitted:
- Reordering any existing members, including stored properties.
- Adding any new members, including stored properties.
- Changing existing properties from stored to computed or vice versa.
- As a special case of the above, adding or removing ``lazy`` from a stored
property.
- Changing the body of any methods, initializers, or accessors.
- Adding or removing an observing accessor (``willSet`` or ``didSet``) to/from
an existing property. This is effectively the same as modifying the body of a
Expand Down Expand Up @@ -651,8 +656,10 @@ properties in a ``@fixedContents`` struct are implicitly declared
Reordering all other members is still permitted.
- Adding new stored instance properties (public or non-public) is not permitted.
Adding any other new members is still permitted.
- Existing instance properties may not be changed from stored to computed or
vice versa.
- Changing existing instance properties from stored to computed or
vice versa is not permitted.
- Similarly, adding or removing ``lazy`` from a stored property is not
permitted.
- 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 permitted if the
Expand All @@ -670,6 +677,12 @@ Additionally, if the type of any stored instance property includes a struct or
enum, that struct or enum must be `versioned <versioned entity>`. This includes
generic parameters and members of tuples.

.. note::

The above restrictions do not apply to ``static`` properties of
``@fixedContents`` structs. Static members effectively behave as top-level
functions and variables.

.. note::

The name ``@fixedContents`` is intentionally awful to encourage us to come
Expand Down Expand Up @@ -787,9 +800,8 @@ clients that the enum cases are exhaustive. In particular:

- Adding new cases is not permitted.
- Reordering existing cases is not permitted.
- Adding a raw type to an enum that does not have one is not permitted -- it's
used for optimization.
- Removing a non-public case is not applicable.
- Adding a raw type is still permitted.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you sure about this?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps @DougGregor or @jckarter knows if adding a raw type has any effects in addition to what you'd get if you wrote the conformance manually?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like I remember some from SE-0192 but perhaps I didn't actually implement them. (I know at one point we tossed around the idea of raw type = trivial one-word or 64-bit representation.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A raw type is just sugar for implementing a RawRepresentable conformance. It doesn't change the representation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay.

- Adding any other members is still permitted.
- Removing any non-public, non-versioned members is still permitted.
- Adding a new protocol conformance is still permitted.
Expand Down Expand Up @@ -827,6 +839,7 @@ 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 requirement may be added as long as it has a default.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about this until we have a generalized existential story.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. This is true for adding new requirements with non-covariant Self, too. I'll add a separate bullet explaining that making something not usable as an existential is binary-compatible but not source-compatible.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah. Even if you already had associated types, I think we should be able to support the "existential of fully-constrained subprotocol" possibly before we get the full generalized existentials. It's a much easier change to reason about, and this would break that too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a radar on me for that :) One day...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amusing thing about binary compatibility: as? P casts written before P gained an associated type will continue to work fine, but the source code, if recompiled, would result in a compiler error.

- A default may be added to an associated type.
- Removing a default from an associated type is a `binary-compatible
source-breaking change`.
Expand All @@ -840,9 +853,18 @@ There are very few safe changes to make to protocols and their members:
be added to a function requirement without any additional versioning
information.

Note that clients can use a protocol as an existential type as long as it does
not have any associated types or requirements containing ``Self`` in
non-covariant position. Therefore adding such a requirement becomes a
`binary-compatible source-breaking change`.

Adding such requirements to protocols that already contain such requirements and
cannot be used as existential types, on the other hand, is always
source-compatible.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the thing I don't want to promise, because of fully-constrained sub-protocols.


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

- Adding a new associated type.
- Adding or removing refined protocols.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooh, good catch.

- Removing any existing requirements (type or non-type).
- Making an existing requirement optional.
- Making a non-``@objc`` protocol ``@objc`` or vice versa.
Expand Down Expand Up @@ -874,6 +896,8 @@ support all of the following changes:

- Reordering any existing members, including stored properties.
- Changing existing properties from stored to computed or vice versa.
- As a special case of the above, adding or removing ``lazy`` from a stored
property.
- Changing the body of any methods, initializers, or accessors.
- Adding or removing an observing accessor (``willSet`` or ``didSet``) to/from
an existing property. This is effectively the same as modifying the body of a
Expand Down Expand Up @@ -1090,13 +1114,20 @@ additive feature, it can be added to the model at any time.
Extensions
~~~~~~~~~~

Non-protocol extensions largely follow the same rules as the types they extend.
Extensions largely follow the same rules as the types they extend.
The following changes are permitted:

- 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.
- Adding any new member.
- Reordering members.
- Removing any non-public, non-versioned member.
- Changing the body of any methods, initializers, or accessors.

Additionally, non-protocol extensions allow a few additional changes:

- 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
Expand All @@ -1105,24 +1136,6 @@ The following changes are permitted:
- 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.


Protocol Extensions
-------------------

Protocol extensions follow slightly different rules from other extensions; the
following changes are permitted:

- Adding new extensions and removing empty extensions.
- Moving a member from one extension to another within the same module, as long
as both extensions have the exact same constraints.
- Adding any new member.
- Reordering members.
- Removing any non-public, non-versioned member.
- Changing the body of any methods, initializers, or accessors.

.. note::

Although it is not related to evolution, it is worth noting that members of
Expand Down