JoeG (and Dmitri before him) pointed out a while back that having
/two/ ways to get something emitted into a client's module was really
more complexity than we really needed, and created a pitfall for
library authors who might choose the wrong one for their needs.
- 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.
- Update the Pygments lexer we use for parsing Swift-like code.
- State more explicitly which highlighting should be used in which
code blocks.
- Disable highlighting altogether in certain cases (such as SIL.rst,
which has equal amounts grammar and SIL excerpts).
This should fix the warnings-as-error issues coming from Sphinx > 1.3.4.
Based on a patch by Jeremy Fergason!
https://bugs.swift.org/browse/SR-620
The main change is that @always_emit_into_client is now not considered a
versioned attribute: either you use it up front and the entity is not part
of your ABI, or you don't and it is. Everything else falls out from that.
Describe a new attribute, @always_emit_into_client, which covers the
behavior of helpers for inlineable functions: any client that makes use
of the body of an inlineable function should use that implementation,
including any helper functions, local functions, or closures referenced
therein. This is also a tool a library developer can use.
This is a nice change because it formalizes several things that were
previously special-cased; however, there are still some open questions.
It's not totally clear whether we want separate @inlineable and
@always_emit_into_client annotations; we could attempt to get away with
just the latter. However, as noted in the diff, there are some entities
that can't really be completely eliminated from the ABI, so marking them
@always_emit_into_client would be disingenuous.
...from JoeG, Dmitri, and David Owens.
- Add an explicit section on default arguments.
- Replace the phrase "permitted but discouraged" with a new and stronger
term "binary-compatible source-breaking change". This may need more
work but it is an improvement.
- Mark that we could make converting get-only 'var' to 'let' safe.
- Adding a required convenience init is safe with certain restrictions.
- Add some more related proposals.
- Add a todo list for more substantive changes and ongoing discussion.
- Assorted clarifications and typo fixes.
...by giving all the types silly magic-themed names, rather than just
'Base' or 'SomeProto'. That makes a (mostly) consistent theme throughout
the document, and hopefully makes it easier to have a mental model
about what various changes mean.
I realized "members are mostly the same as their top-level equivalents" is worth
calling out explicitly, especially for subscripts and initializers without top-level
equivalents. There's still a hole here for members of protocol extensions, which can
have pretty drastic effects on conforming types.
"Proposal" refers to something going through the Swift Evolution Process,
which this won't as such. (Although it does have many pieces affected by
proposals, as described at the end of the document.)
Basically, elaborate on why it's not important right now. Also, drop the
section on limiting the addition of new vtable-dispatched methods. That's
not something we're really interested in.
The Default Behavior Should Be Safe
Also, remove the line about "providing tools to check changes", because
it no longer fits in the prologue flow and isn't core to the model.
The section on it is good enough.
I went through the list of attributes and declaration modifiers and
made sure they were all accounted for. Anything not on the list
should be assumed restricted, as mentioned at the top of the
"Supported Evolution" section.
...most of which don't exist yet. These are things that need to go
through the Swift Evolution Process and ultimately be accepted or
rejected before we have final answers on some parts of the document.
Specifically, public members (and nested types) within a versioned type are
assumed to be present on the outer type since its introduction unless otherwise
specified. (This saves boilerplate for a type's initial API.)
Jordan Rose
practicalswift
Manav Gabhawala
Dmitri Gribenko