Skip to content

Commit 773f0b8

Browse files
authored
Update the ABI stability section of the proposal template
1 parent 61e0230 commit 773f0b8

File tree

1 file changed

+52
-18
lines changed

1 file changed

+52
-18
lines changed

proposal-templates/0000-swift-template.md

Lines changed: 52 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -65,24 +65,58 @@ aid in migration?
6565

6666
## Effect on ABI stability
6767

68-
Does the proposal change the ABI of existing language features? The
69-
ABI comprises all aspects of the code generation model and interaction
70-
with the Swift runtime, including such things as calling conventions,
71-
the layout of data types, and the behavior of dynamic features in the
72-
language (reflection, dynamic dispatch, dynamic casting via `as?`,
73-
etc.). Purely syntactic changes rarely change existing ABI. Additive
74-
features may extend the ABI but, unless they extend some fundamental
75-
runtime behavior (such as the aforementioned dynamic features), they
76-
won't change the existing ABI.
77-
78-
Features that don't change the existing ABI are considered out of
79-
scope for [Swift 4 stage 1](README.md). However, additive features
80-
that would reshape the standard library in a way that changes its ABI,
81-
such as [where clauses for associated
82-
types](https://github.com/apple/swift-evolution/blob/master/proposals/0142-associated-types-constraints.md),
83-
can be in scope. If this proposal could be used to improve the
84-
standard library in ways that would affect its ABI, describe them
85-
here.
68+
The ABI comprises all aspects of how code is generated for the
69+
language and how that code interacts with the Swift runtime library.
70+
It includes such things as calling conventions, function signatures,
71+
the layout of data types, and the behavior of dynamic features in
72+
the language ssuch as reflection, dynamic dispatch, and dynamic
73+
casting. It also includes things such as the addition of functions
74+
and types to the public symbols of a library.
75+
76+
Many language proposals have no direct impact on the ABI. For
77+
example, a proposal to add the `typealias` declaration would have
78+
no effect on the ABI because type aliases are not represented
79+
dynamically and uses of them in code can be straightforwardly
80+
translated into uses of the aliased type. Such proposals can
81+
simply state in this section that they have no impact on the ABI.
82+
However, if *using* the feature in code that must maintain a stable
83+
ABI can have a surprising ABI impact, that should be discussed
84+
in this section.
85+
86+
Because Swift has a stable ABI on some platforms, proposals are
87+
generally not acceptable if they would require changes to the ABI
88+
of existing language features or declarations. For example,
89+
Swift could not accept a feature which, in order to work, would
90+
require parameters with certain types to always be passed as owned
91+
values, because parameters are not always passed as owned values
92+
in the ABI. Proposals must be designed to avoid the need for this.
93+
For example, the feature above might only be enabled for parameters
94+
marked a special way, and then adding that marking to an existing
95+
function parameter would change the ABI of that function.
96+
97+
Proposals are acceptable if they can be thought of as merely
98+
*adding* to the ABI, such as by adding new kinds of declarations,
99+
adding new modifiers or attributes that can be used on existing
100+
kinds of declarations, or adding new types or methods to the Swift
101+
standard library. On platforms with stable ABIs, such features
102+
will by default require a new release of the platform in order
103+
to work, and so their use in code that may deploy to older
104+
releases will have to be availability-guarded. If this limitation
105+
applies to any part of this proposal, that should be discussed
106+
in this section.
107+
108+
Adding a function to the standard library does not always require
109+
an addition to the ABI if it can be implemented using other
110+
library functions. Library maintainers may be able to help you
111+
with this during the code review of your implementation. Adding
112+
a type or protocol always requires an addition to the ABI.
113+
114+
If a feature does require additions to the ABI, platforms with
115+
stable ABIs may sometimes be able to back-deploy those additions
116+
to existing releases of the platform. This is not always possible,
117+
and in any case, it is outside the scope of the evolution process.
118+
Proposals should usually discuss ABI stability concerns as if
119+
it was not possible to back-deploy the necessary ABI additions.
86120

87121
## Effect on API resilience
88122

0 commit comments

Comments
 (0)