Update README, process, and proposal template for Swift 4 stage 1. (#541)

* Update README, process, and proposal template for Swift 4 stage 1.

* Fix minor review comments

* Move information about previous releases into separate files.

Moving out information about Swift 2.2 and Swift 3.0 allows us to be
more verbody there (about which proposals were implemented in a
release) and keep the README more forward-looking.

* Fix a typo in the README

Author: DougGregor

0000-template.md

@@ -44,13 +44,55 @@ comments detailing what it does. The detail in this section should be
 sufficient for someone who is *not* one of the authors to be able to
 reasonably implement the feature.
 
-## Impact on existing code
-
-Describe the impact that this change will have on existing code. Will some
-Swift applications stop compiling due to this change? Will applications still
-compile but produce different behavior than they used to? Is it
-possible to migrate existing Swift code to use a new feature or API
-automatically?
+## Source compatibility
+
+Relative to the Swift 3 evolution process, the source compatibility
+requirements for Swift 4 are *much* more stringent: we should only
+break source compatibility if the Swift 3 constructs were actively
+harmful in some way, the volume of affected Swift 3 code is relatively
+small, and we can provide source compatibility (in Swift 3
+compatibility mode) and migration.
+
+Will existing correct Swift 3 or Swift 4 applications stop compiling
+due to this change? Will applications still compile but produce
+different behavior than they used to? If "yes" to either of these, is
+it possible for the Swift 4 compiler to accept the old syntax in its
+Swift 3 compatibility mode? Is it possible to automatically migrate
+from the old syntax to the new syntax? Can Swift applications be
+written in a common subset that works both with Swift 3 and Swift 4 to
+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.
+
+## Effect on API resilience
+
+API resilience describes the changes one can make to a public API
+without breaking its ABI. Does this proposal introduce features that
+would become part of a public API? If so, what kinds of changes can be
+made without breaking ABI? Can this feature be added/removed without
+breaking ABI? For more information about the resilience model, see the
+[library evolution
+document](https://github.com/apple/swift/blob/master/docs/LibraryEvolution.rst)
+in the Swift repository.
 
 ## Alternatives considered
 

README.md

@@ -20,94 +20,80 @@ historical purposes, but are not necessarily indicative of the
 features shipped. The release notes for each shipped version are the
 definitive list of notable changes in each release.
 
-## Development major version:  Swift 3.0
-
-Expected release date: Late 2016
-
-The primary goal of this release is to solidify and mature the Swift language and
-development experience.  While source breaking changes to the language have been
-the norm for Swift 1 through 3, we would like the Swift 3.x (and Swift 4+)
-languages to be as *source compatible* with Swift 3.0 as reasonably possible.
-However, this will still be best-effort: if there is a really good reason to
-make a breaking change beyond Swift 3, we will consider it and find the least
-invasive way to roll out that change (e.g. by having a long deprecation cycle).
-
-To achieve this end, Swift 3 focuses on getting the basics right for the
-long term: 
-
-* **API design guidelines**: The way in which Swift is used in popular
-  libraries has almost as much of an effect on the character of Swift
-  code as the Swift language itself. The [API naming and design
-  guidelines](https://swift.org/documentation/api-design-guidelines/) are a
-  carefully crafted set of guidelines for building great Swift APIs.
-
-* **Automatic application of naming guidelines to imported Objective-C APIs**:
-  When importing Objective-C APIs, the Swift 3 compiler 
-  [automatically maps](proposals/0005-objective-c-name-translation.md) methods
-  into the new Swift 3 naming guidelines, and provides a number of Objective-C
-  features to control and adapt this importing.
-
-* **Adoption of naming guidelines in key APIs**: The Swift Standard Library has
-  been significantly overhauled to embrace these guidelines, and key libraries
-  like [Foundation](proposals/0069-swift-mutability-for-foundation.md) and
-  [libdispatch](proposals/0088-libdispatch-for-swift3.md) have seen major
-  updates, which provide the consistent development experience we seek.
-
-* **Swiftification of imported Objective-C APIs**: Beyond the naming guidelines,
-  Swift 3 provides an improved experience for working with Objective-C APIs.
-  This includes importing
-  [Objective-C generic classes](proposals/0057-importing-objc-generics.md),
-  providing the ability to [import C APIs](proposals/0044-import-as-member.md)
-  into an "Object Oriented" style, much nicer
-  [imported string enums](proposals/0033-import-objc-constants.md), safer
-  syntax to work with [selectors](proposals/0022-objc-selectors.md) and
-  [keypaths](proposals/0062-objc-keypaths.md), etc.
-
-* **Focus and refine the language**: Since Swift 3 is the last release to make
-  major source breaking changes, it is also the right release to reevaluate the
-  syntax and semantics of the core language.  This means that some obscure or
-  problematic features will be removed, we focus on improving consistency of
-  syntax in many small ways (e.g. by 
-  [revising handling of parameter labels](proposals/0046-first-label.md), and
-  focus on forward looking improvements to the type system.  This serves the
-  overall goal of making Swift a simpler, more predictable, and more consistent
-  language over the long term.
-
-* **Improvements to tooling quality**: The overall quality of the compiler is
-  really important to us: it directly affects the joy of developing in Swift.
-  Swift 3 focuses on fixing bugs in the compiler and IDE features, improving the
-  speed of compile times and incremental builds, improving the performance of
-  the generated code, improving the precision of error and warning messages, etc.
-
-One of the reasons that stability is important is that **portability** to non-Apple
-systems is also a strong goal of Swift 3.  This release enables
-broad scale adoption across multiple platforms, including significant
-functionality in the [Swift core libraries](https://swift.org/core-libraries/)
-(Foundation, libdispatch, XCTest, etc).  A useful Linux/x86 port is
-already available (enabling many interesting server-side scenarios), and work is
-underway across the community to bring Swift to FreeBSD, Raspberry Pi, Android,
-Windows, and others.  While we don't know which platforms will reach a useful
-state by the launch of Swift 3, significant effort continues to go into making
-the compiler and runtime as portable as practically possible.
-
-Finally, Swift 3 also includes a mix of relatively small but important additions
-to the language and standard library that make solving common problems easier and
-make everything feel nicer.  A detailed list of accepted proposals is included
-on the [proposal status page][proposal-status].
-
-
-## Swift 2.2 - Released on March 21, 2016
-
-[This release](https://swift.org/blog/swift-2-2-released/) focused on fixing
-bugs, improving quality-of-implementation (QoI)
-with better warnings and diagnostics, improving compile times, and improving
-performance.  It put some finishing touches on features introduced in Swift 2.0, 
-and included some small additive features that don't break Swift code or
-fundamentally change the way Swift is used. As a step toward Swift 3, it
-introduced warnings about upcoming source-incompatible changes in Swift 3
-so that users can begin migrating their code sooner.
-
-Aside from warnings, a major goal of this release was to be as source compatible
-as practical with Swift 2.0.
+## Development major version:  Swift 4.0
+
+Expected release date: Late 2017
+
+The Swift 4 release is designed around two primary goals: to provide
+source stability for Swift 3 code and to provide ABI stability for the
+Swift standard library. To that end, the Swift 4 release will be
+divided into two stages.
+
+Stage 1 focuses on the essentials required for source and ABI
+stability. Features that don't fundamentally change the ABI of
+existing language features or imply an ABI-breaking change to the
+standard library will not be considered in this stage.
+
+Stage 2 will commence once the implementation work on the Stage 1
+features is cresting, and can contain a few other large and small
+features. We expect that stage 2 will commence some time in Spring
+2017.
+
+The high-priority features supporting stage 1's source and ABI
+stability goals are:
+
+* Source stability features: the Swift language will need [some
+  accommodations](https://github.com/apple/swift-evolution/blob/master/proposals/0141-available-by-swift-version.md)
+  to support code bases that target different language versions, to
+  help Swift deliver on its source-compatibility goals while still
+  enabling rapid progress.
+
+* Resilience: resilience provides a way for public APIs to evolve over
+  time, while maintaining a stable ABI. For example, resilience
+  eliminates the [fragile base class
+  problem](https://en.wikipedia.org/wiki/Fragile_base_class) that
+  occurs in some object-oriented languages (e.g., C++) by describing
+  the types of API changes that can be made without breaking ABI
+  (e.g., "a new stored property or method can be added to a class").
+
+* Stabilizing the ABI: There are a ton of small details that need to
+  be audited and improved in the code generation model, including
+  interaction with the Swift runtime. While not specifically
+  user-facing, the decisions here affect performance and (in some rare
+  cases) the future evolution of Swift.
+
+* Generics improvements needed by the standard library: the standard
+  library has a number of workarounds for language deficiencies, many
+  of which manifest as extraneous underscored protocols and
+  workarounds. If the underlying language deficiencies remain, they
+  become a permanent part of the stable ABI. [Conditional
+  conformances](https://github.com/apple/swift-evolution/blob/master/proposals/0143-conditional-conformances.md),
+  [recursive protocol
+  requirements](https://github.com/apple/swift/blob/master/docs/GenericsManifesto.md#recursive-protocol-constraints-),
+  and [where clauses for associated
+  types](https://github.com/apple/swift-evolution/blob/master/proposals/0142-associated-types-constraints.md)
+  are known to be in this category, but it's plausible that other
+  features will be in scope if they would be used in the standard
+  library.
+
+* String re-evaluation: String is one of the most important
+  fundamental types in the language. Swift 4 seeks to make strings more
+  powerful and easier-to-use, while retaining Unicode correctness by
+  default.
+
+* Memory ownership model: an (opt-in) Cyclone/Rust-inspired memory
+  ownership model is highly desired by systems programmers and for
+  other high-performance applications that want predictible and
+  deterministic performance. This feature will fundamentally shape the
+  ABI, from low-level language concerns such as "inout" and low-level
+  "addressors" to its impact on the standard library. While a full
+  memory ownership model is likely too large for Swift 4 stage 1, we
+  need a comprehensive design to understand how it will change the
+  ABI.
+
+## Previous releases
+
+* [Swift 3.0](releases/swift-3_0.md) - Released on September 13, 2016
+* [Swift 2.2](releases/swift-2_2.md) - Released on March 21, 2016
 
 [proposal-status]: https://apple.github.io/swift-evolution/

process.md

@@ -45,7 +45,12 @@ Please state explicitly whether you believe that the proposal should be accepted
 ## How to propose a change
 
 * **Check prior proposals**: many ideas come up frequently, and may either be in active discussion on the mailing list, or may have been discussed already and have joined the [Commonly Rejected Proposals](commonly_proposed.md) list.  Please check the mailing list archives and this list for context before proposing something new.
-
+* **Consider the goals of the upcoming Swift release**: Each major
+Swift release is focused on a [specific set of goals](README.md)
+described early in the release cycle. When proposing a change to
+Swift, please consider how your proposal fits in with the larger goals
+of the upcoming Swift release. Proposals that are clearly out of scope
+for the upcoming Swift release will not be brought up for review. If you can't resist discussing a proposal that you know is out of scope, please include the tag `[Out of scope]` in the subject.
 * **Socialize the idea**: propose a rough sketch of the idea on the [swift-evolution mailing list][swift-evolution-mailing-list], the problems it solves, what the solution looks like, etc., to gauge interest from the community.
 * **Develop the proposal**: expand the rough sketch into a complete proposal, using the [proposal template](0000-template.md), and continue to refine the proposal on the evolution mailing list. Prototyping an implementation and its uses along with the proposal is encouraged, because it helps ensure both technical feasibility of the proposal as well as validating that the proposal solves the problems it is meant to solve.
 * **Request a review**: initiate a pull request to the [swift-evolution repository][swift-evolution-repo] to indicate to the core team that you would like the proposal to be reviewed. When the proposal is sufficiently detailed and clear, and addresses feedback from earlier discussions of the idea, the pull request will be accepted. The proposal will be assigned a proposal number as well as a core team member to manage the review.

releases/swift-2_2.md

@@ -0,0 +1,23 @@
+# Swift 2.2 - Released on March 21, 2016
+
+[This release](https://swift.org/blog/swift-2-2-released/) focused on fixing
+bugs, improving quality-of-implementation (QoI)
+with better warnings and diagnostics, improving compile times, and improving
+performance.  It put some finishing touches on features introduced in Swift 2.0, 
+and included some small additive features that don't break Swift code or
+fundamentally change the way Swift is used. As a step toward Swift 3, it
+introduced warnings about upcoming source-incompatible changes in Swift 3
+so that users can begin migrating their code sooner.
+
+Aside from warnings, a major goal of this release was to be as source compatible
+as practical with Swift 2.0.
+
+## Evolution proposals included in Swift 2.2
+
+* [SE-0001: Allow (most) keywords as argument labels](https://github.com/apple/swift-evolution/blob/master/proposals/0001-keywords-as-argument-labels.md)
+* [SE-0015: Tuple comparison operators](https://github.com/apple/swift-evolution/blob/master/proposals/0015-tuple-comparison-operators.md)
+* [SE-0014: Constraining `AnySequence.init`](https://github.com/apple/swift-evolution/blob/master/proposals/0014-constrained-AnySequence.md)
+* [SE-0011: Replace `typealias` keyword with `associatedtype` for associated type declarations](https://github.com/apple/swift-evolution/blob/master/proposals/0011-replace-typealias-associated.md)
+* [SE-0021: Naming Functions with Argument Labels](https://github.com/apple/swift-evolution/blob/master/proposals/0021-generalized-naming.md)
+* [SE-0022: Referencing the Objective-C selector of a method](https://github.com/apple/swift-evolution/blob/master/proposals/0022-objc-selectors.md)
+* [SE-0020: Swift Language Version Build Configuration](https://github.com/apple/swift-evolution/blob/master/proposals/0020-if-swift-version.md)