Merge pull request #1616 from apple/abi-stability-rewrite

Update the ABI stability section of the proposal template

Author: rjmccall

proposal-templates/0000-swift-template.md

@@ -65,24 +65,69 @@ aid in migration?
 
 ## Effect on ABI stability
 
-Does the proposal change the ABI of existing language features? The
-ABI comprises all aspects of the code generation model and interaction
-with the Swift runtime, including such things as calling conventions,
-the layout of data types, and the behavior of dynamic features in the
-language (reflection, dynamic dispatch, dynamic casting via `as?`,
-etc.). Purely syntactic changes rarely change existing ABI. Additive
-features may extend the ABI but, unless they extend some fundamental
-runtime behavior (such as the aforementioned dynamic features), they
-won't change the existing ABI.
-
-Features that don't change the existing ABI are considered out of
-scope for [Swift 4 stage 1](README.md). However, additive features
-that would reshape the standard library in a way that changes its ABI,
-such as [where clauses for associated
-types](https://github.com/apple/swift-evolution/blob/master/proposals/0142-associated-types-constraints.md),
-can be in scope. If this proposal could be used to improve the
-standard library in ways that would affect its ABI, describe them
-here.
+The ABI comprises all aspects of how code is generated for the
+language, how that code interacts with other code that has been
+compiled separately, and how that code interacts with the Swift
+runtime library.  It includes the basic rules of the language ABI,
+such as calling conventions, the layout of data types, and the
+behavior of dynamic features in the language like reflection,
+dynamic dispatch, and dynamic casting.  It also includes applications
+of those basic rules to ABI-exposed declarations, such as the `public`
+functions and types of ABI-stable libraries like the Swift standard
+library.
+
+Many language proposals have no direct impact on the ABI.  For
+example, a proposal to add the `typealias` declaration to Swift
+would have no effect on the ABI because type aliases are not
+represented dynamically and uses of them in code can be
+straightforwardly translated into uses of the aliased type.
+Proposals like this can simply state in this section that they
+have no impact on the ABI.  However, if *using* the feature in code
+that must maintain a stable ABI can have a surprising ABI impact,
+for example by changing a function signature to be different from
+how it would be without using the feature, that should be discussed
+in this section.
+
+Because Swift has a stable ABI on some platforms, proposals are
+generally not acceptable if they would require changes to the ABI
+of existing language features or declarations.  Proposals must be
+designed to avoid the need for this.
+
+For example, Swift could not accept a proposal for a feature which,
+in order to work, would require parameters of certain (existing)
+types to always be passed as owned values, because parameters are
+not always passed as owned values in the ABI.  This feature could
+be fixed by only enabling it for parameters marked a special new way.
+Adding that marking to an existing function parameter would change
+the ABI of that specific function, which programmers can make good,
+context-aware decisions about: adding the marking to an existing
+function with a stable ABI would not be acceptable, but adding it
+to a new function or to a function with no stable ABI restrictions
+would be fine.
+
+Proposals that change the ABI may be acceptable if they can be thought
+of as merely *adding* to the ABI, such as by adding new kinds of
+declarations, adding new modifiers or attributes, or adding new types
+or methods to the Swift standard library.  The key principle is
+that the ABI must not change for code that does not use the new
+feature.  On platforms with stable ABIs, uses of such features will
+by default require a new release of the platform in order to work,
+and so their use in code that may deploy to older releases will have
+to be availability-guarded.  If this limitation applies to any part
+of this proposal, that should be discussed in this section.
+
+Adding a function to the standard library does not always require
+an addition to the ABI if it can be implemented using existing
+functions.  Library maintainers may be able to help you with this
+during the code review of your implementation.  Adding a type or
+protocol currently always requires an addition to the ABI.
+
+If a feature does require additions to the ABI, platforms with
+stable ABIs may sometimes be able to back-deploy those additions
+to existing releases of the platform.  This is not always possible,
+and in any case, it is outside the scope of the evolution process.
+Proposals should usually discuss ABI stability concerns as if
+it was not possible to back-deploy the necessary ABI additions.
 
 ## Effect on API resilience