[Heads up] Upcoming review of API Design Guidelines, Standard Library API, and Clang Importer changes

(Douglas Gregor) #1

Hi all,

One of the major goals of Swift 3 is to introduce a set of API Design Guidelines for Swift and to apply those guidelines to both the Standard Library APIs and to imported (Objective-)C APIs. This initiative is described in more detail in the blog entry at


We are going to initiate a public review of this work starting next Wednesday (January 20th) and running through the end of the month. The scale of the effort is far larger than anything else we’ve handled in the evolution process, comprising three related pieces:

  * API Design Guidelines: https://swift.org/documentation/api-design-guidelines.html (TODO: create a skeleton proposal in swift-evolution to link to)
  * Standard library API changes: https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md
  * Clang importer changes: https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md

We’ll handle this as three separate reviews (one per document) running concurrently. The concurrency is important because there is a lot of interplay between the different moving parts (e.g., an API change in the standard library will correspond to a particular guideline, or an importer rule implements a particular guideline, etc.). Yet, there is likely to be specific per-document feedback, and we benefit from having separate discussion threads.

We’re still getting all of the pieces together for the review, and these documents will change up until the public review period begins. Feel free to browse through the documents and the other references mentioned in the blog. However, we request that everyone hold off on discussion of the documents until the public review begins, so that we’re all talking about the exact same documents, and that you familiarize yourself with all three documents before participating in the public review of any of them (because they are so closely linked).