Skip to content

Add a new proposal: 0006 Apply API Guidelines to the Standard Library #1

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 4 commits into from
Dec 3, 2015
Merged

Add a new proposal: 0006 Apply API Guidelines to the Standard Library #1

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
12f0033
Add a new proposal: 0006 Apply API Guidelines to the Standard Library
gribozavr Dec 2, 2015
a251786
Address review feedback
gribozavr Dec 3, 2015
e6498ce
Actually point the link to the swift-3-api-guidelines branch
gribozavr Dec 3, 2015
4d4ef04
Add a clarification that the list is not exhaustive
gribozavr Dec 3, 2015
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
54 changes: 54 additions & 0 deletions proposals/0006-apply-api-guidelines-to-the-standard-library.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Apply API Guidelines to the Standard Library

* Proposal: [SE-0006](https://github.com/apple/swift-evolution/proposals/0006-apply-api-guidelines-to-the-standard-library.md)
* Author(s): [Dave Abrahams](https://github.com/dabrahams), [Dmitri Gribenko](https://github.com/gribozavr), [Maxim Moiseev](https://github.com/moiseev)
* Status: **Awaiting Review**
* Review manager: [Doug Gregor](https://github.com/DougGregor)

## Introduction

[Swift API Design Guidelines][api-design-guidelines] being developed as
part of Swift 3. It is important that the Standard Library is an exemplar of
Swift API Design Guidelines: the APIs from the Standard Library are, probably,
the most frequently used Swift APIs in any application domain; the Standard
Library also sets precedent for other libraries.

In this project, we are reviewing the entire Standard Library and updating it
to follow the guidelines.

## Proposed solution

The actual work is being performed on the [swift-3-api-guidelines
branch][swift-3-api-guidelines-branch] of the [Swift repository][swift-repo].
On high level, the changes can be summarized as follows.

* Strip `Type` suffix from remaining protocol names. In a few special cases
this means adding a `Protocol` suffix to get out of the way of type
names that are primary (though most of these we expect to be
obsoleted by Swift 3 language features).

* The concept of `generator` is renamed to `iterator`.

* `IndexingGenerator` is renamed to `DefaultCollectionIterator`.

**More changes will be summarized here as they are implemented.**

## API diffs

Differences between Swift 2.2 Standard library API and the proposed API are
added to this section as they are being implemented on the
[swift-3-api-guidelines branch][swift-3-api-guidelines-repo].

## Impact on existing code

The proposed changes are massively source-breaking for Swift code, and will
require a migrator to translate Swift 2 code into Swift 3 code. The API diffs
from this proposal will be the primary source of the information about the
required transformations. In addition, to the extent the language allows, the
library will keep old names as unavailable symbols with a `renamed` annotation,
that allows the compiler to produce good error messages and emit Fix-Its.

[api-design-guidelines]: https://swift.org/documentation/api-design-guidelines.html "API Design Guidelines"
[swift-repo]: https://github.com/apple/swift "Swift repository"
[swift-3-api-guidelines-branch]: https://github.com/apple/swift/tree/swift-3-api-guidelines "Swift 3 API Design Guidelines preview"