Skip to content

Update the ABI stability section of the proposal template #1616

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.

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 4 commits into from
Apr 19, 2022
Merged
Changes from all commits
Commits
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
81 changes: 63 additions & 18 deletions proposal-templates/0000-swift-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down