Update Revision History to Clarify Language Evolution

tadbyt commented 8 months ago

Location

https://docs.swift.org/swift-book/documentation/the-swift-programming-language/revisionhistory

Description

Update the Revision History to link each language release with the corresponding https://www.swift.org/blog/ entry, for those that have one. This could be done by making the language version a hyperlink to the corresponding blog entry. Based on what is provided on https://www.swift.org/blog/ , the following is what is currently readily available to link to:

While that wouldn't cover all of the minor releases, it should be enough. Perhaps a note directing those interested to the Swift Evolution dashboard.

Motivation

The Swift Programming Language serves as the de facto language specification for Swift. However, while its Revision History identifies the textual changes as the document has been revised, it does not clearly reflect the underlying language evolution. That is given as a set of Swift Evolution (SE) proposals that are implemented for each language version. This change could also provide insight to users of The Swift Programming Language when encountering behavior in their code which doesn’t match the book, potentially identifying other defects and deficiencies that have crept into the document as Swift has evolved as well as those features that are yet to be documented.

Alternatives Considered

Updating the Revision History to identify the set of SE proposals incorporated into each version of the language, with the title of each SE proposal serving as a hyperlink to the corresponding SE proposal. This change would provide a succinct and accurate description of what changed from one version of the Swift to the next.

tadbyt commented 8 months ago

A review of the SE proposals as of December 19, 2023, yields the following:

• Implemented in Swift 5.9.2 o SE-0407: Member Macro Conformances

• Implemented in Swift 5.9 o SE-0402: Generalize conformance macros as extension macros o SE-0401: Remove Actor Isolation Inference caused by Property Wrappers o SE-0400: Init Accessors o SE-0399: Tuple of value pack expansion o SE-0398: Allow Generic Types to Abstract Over Packs o SE-0397: Freestanding Declaration Macros o SE-0396: Conform Never to Codable o SE-0395: Observation o SE-0394: Package Manager Support for Custom Macros o SE-0393: Value and Type Parameter Packs o SE-0392: Custom Actor Executors o SE-0391: Package Registry Publish o SE-0390: Noncopyable structs and enums o SE-0389: Attached Macros o SE-0398. Convenience Async[Throwing]Stream.makeStream Methods o SE-0386: New access modifier: package o SE-0384: Importing Forward Declared Objective-C Interfaces and Protocols o SE-0382: Expression Macros o SE-0381: DiscardingTaskGroups o SE-0380: if and switch Expressions o SE-0377: borrowing and consuming Parameter Ownership Modifiers o SE-0374: Add sleep(for:) to Clock o SE-0366: consume Operator to End the Lifetime of a Variable Binding

• Implemented in Swift 5.8 o SE-0378: Package Registry Authentication o SE-0376: Function Back Deployment o SE-0375: Opening existential arguments to optional parameters o SE-0373: Lift all limitations on variables in result builders o SE-0372: Document Sorting as Stable o SE-0370: Pointer Family Initialization Improvements and Better Buffer Slices o SE-0369: Add CustomDebugStringConvertible conformance to AnyKeyPath o SE-0368: StaticBight o SE-0367: Conditional compilation for attributes o SE-0365: Allow implicit self for weak self captures, after self is unwrapped o SE-0362: Piecemeal adoption of upcoming language improvements o SE-0274: Concise magic file names

• Implemented in Swift 5.7 o SE-0363: Unicode for String Processing o SE-0361: Opaque result types with limited availability o SE-0358: Primary Associated Types in the Standard Library o SE-0357: Regex-powered string processing algorithms o SE-0356: Swift Snippets o SE-0355: Regex Syntax and Run-time Construction o SE-0354: Regex Literals o SE-0353: Constrained Existential Types o SE-0352: Implicitly Opened Existentials o SE-0351: Regex builder DSL o SE-0350: Regex Type and Overview o SE-0349: Unaligned Loads and Stores from Raw Memory o SE-0348: buildPartialBlock for result builders o SE-0347: Type inference from default expressions o SE-0346: Lightweight same-type requirements for primary associated types o SE-0345: if let shorthand for shadowing an existing optional variable o SE-0344: Distributed Actor Runtime o SE-0343: Concurrency in Top-level Code o SE-0341: Opaque Parameter Declarations o SE-0340: Unavailable From Async Attribute o SE-0339: Module Aliasing For Disambiguation o SE-0338: Clarify the Execution of Non-Actor-Isolated Async Functions o SE-0336: Distributed Actor Isolation o SE-0334: Pointer API Usability Improvements o SE-0333: Expand usability of withMemoryRebound o SE-0329: Clock, Instant, and Duration o SE-0328: Structural opaque result types o SE-0326: Enable multi-stateement closure parameter/result type inference o SE-0309: Unlock existentials for all protocols o SE-0302: Sendable and @Sendable closures o SE-0292: Package Registry Service

• Implemented in Swift 5.6 o SE-0337: Incremental migration to concurrency checking o SE-0335: Introduce existential any o SE-0332: Package Manager Command Plugins o SE-0331: Remove Sendable conformance from unsafe pointer types o SE-0325: Additional Package Plugin APIs o SE-0324: Relax diagnostics for pointer arguments to C functions o SE-0322: Temporary uninitialized buffers o SE-0320: Allow codding of non String / Int keyed Dictionary into a KeyedContainer o SE-0315: Type placeholders (formerly, “Placeholder types”) o SE-0305: Package Manager Binary Target Improvements o SE-0303: Package Manager Extensible Build Tools o SE-0290: Unavailability Condition

• Implemented in Swift 5.5.2 o SE-0323: Asynchronous Main Semantics

• Implemented in Swift 5.5 o SE-0319: Conform Never to Identifiable o SE-0317: async let bindings o SE-0316: Global actors o SE-0314: AsyncStream and AsyncThrowingStream o SE-0313: Improved control over actor isolation o SE-0311: Task Local Values o SE-0310: Effectful Read-only Properties o SE-0308: if for postfix member expressions o SE-0307: Allow interchangeable use of CGFloat and Double types o SE-0306: Actors o SE-0304: Structured concurrency o SE-0300: Continuations for interfacing async tasks with synchronous code o SE-0299: Extending Static Member Lookup in Generic Contexts o SE-0298: Async/Await: Sequences o SE-0297: Concurrency Interoperability with Objective-C o SE-0296: Async/await o SE-0295: Codable synthesis for enums with associated values o SE-0293: Extend Property Wrappers to Function and Closure Parameters o SE-0291: Package Collections

• Implemented in Swift 5.4 o SE-0294: Declaring executable targets in Package Manifests o SE-0289: Result builders o SE-0287: Extend implicit member syntax to cover chains of member references o SE-0284: Allow Multiple Variadic Parameters in Functions, Subscripts, and Initializers

• Implemented in Swift 5.3 o SE-0286: Forward-scan matching for trailing closures o SE-0285: Ease the transition to concise magic file strings o SE-0282: Clarify the Swift memory consistency model * o SE-0281: @main: Type-Based Program Entry Points o SE-0280: Enum cases as protocol witnesses o SE-0279: Multiple Trailing Closures o SE-0278: Package Manager Localized Resources o SE-0277: Float16 o SE-0276: Multi-Pattern Catch Clauses o SE-0273: Package Manager Conditional Target Dependencies o SE-0272: Package Manager Binary Dependencies o SE-0271: Package Manager Resources o SE-0269: Increase availability of implicit self in @escaping closures when reference cycles are unlikely to occur o SE-0268: Refine didSet Semantics o SE-0267: where clauses on contextually generic declarations o SE-0266: Synthesized Comparable conformance for enum types o SE-0263: Add a String Initializer with Access to Uninitialized Storage

• Implemented in Swift 5.2 o SE-0253: Callable values of user-defined nominal types o SE-0249: Key Path Expressions as Functions o SE-0226: Package Manager Target Based Dependency Resolution

• Implemented in Swift 5.1 o SE-0261: Identifiable Protocol o SE-0260: Library Evolution for Stable ABIs o SE-0258: Property Wrappers o SE-0255: Implicit returns from single-expression functions o SE-0254: Static and class subscripts o SE-0252: Key Path Member Lookup o SE-0251: SIMD additions o SE-0248: String Gaps and Missing APIs o SE-0247: Contiguous Strings o SE-0245: Add an Array Initializer with Access to Uninitialized Storage o SE-0244: Opaque Result Types o SE-0242: Synthesize default values for the memberwise initializer o SE-0240: Ordered Collection Diffing o SE-0068: Expanding Swift Self to class members and value types

• Implemented in Swift 5.0 o SE-0241: Deprecate String Index Encoded Offsets o SE-0239: Add Codable conformance to Range types o SE-0238: Package Manager Target Specific Build Settings o SE-0237: Introduce withContiguous{Mutable}StorageAvailable methods o SE-0236: Package Manager Platform Deployment Settings o SE-0235: Add Result to the Standard Library o SE-0234: Remove Sequence.SubSequence o SE-0233: Make Numeric Refine a new AdditiveArithmetic Protocol o SE-0232: Remove Some Customization Points from the Standard Library’s Collection Hierarchy o SE-0230: Flatten nested optionals resulting from ‘try?’ o SE-0229: SIMD Vectors o SE-0228: Fix ExpressibleByStringInterpolation o SE-0227: Identify key path o SE-0225: Adding isMultiple to BinaryInteger o SE-0224: Support ‘less than’ operator in compilation conditions o SE-0221: Character Properties o SE-0219: Package Manager Dependency Mirroring o SE-0218: Introduce compactMapValues to Dictionary o SE-0216: Introduce user-defined dynamically “callable” types o SE-0215: Conform Never to Equatable and Hashable o SE-0214: Renaming the DictionaryLiteral type to KeyValuePairs o SE-0213: Literal initialization via coercion o SE-0211: Add Unicode Properties to Unicode.Scalar o SE-0200: Enhancing String Literals Delimiters to Support Raw Text o SE-0192: Handling Future Enum Cases

• Implemented in Swift 4.2 o SE-0212: Compiler Version Directive o SE-0210: Add an offset(of:) method to MemoryLayout o SE-0209: Package Manager Swift Language Version API Update o SE-0208: Package Manager System Library Targets o SE-0207: Add an allSatisfy algorithm to Sequence o SE-0206: Hashable Enhancements o SE-0205: withUnsafePointer(to::) and withUnsafeBytes(of::) for immutable values o SE-0204: Add last(where:) and lastIndex(where:) Methods o SE-0202: Random Unification o SE-0201: Package Manager Local Dependencies o SE-0199: Adding toggle to Bool o SE-0197: Adding in-place removeAll(where:) to the Standard Library o SE-0196: Compiler Diagnostic Directives o SE-0195: Introduce User-defined “Dynamic Member Lookup” Types o SE-0194: Derived Collection of Enum Cases o SE-0193: Cross-module inlining and specialization o SE-0174: Change RangeReplaceableCollection.filter to return Self o SE-0143: Conditional conformances o SE-0079: Allow using optional binding to upgrade self from a weak to strong reference o SE-0054: Abolish ImplicitlyUnwrappedOptional type

• Implemented in Swift 4.1 o SE-0198: Playground QuickLook API Revamp o SE-0191: Eliminate IndexDistance from Collection o SE-0190: Target environment platform condition o SE-0189: Restrict Cross-module Struct Initializers o SE-0188: Make Standard Library Index Types Hashable o SE-0187: Introduce Sequence.compactMap(_:) o SE-0186: Remove ownership keyword support in protocols o SE-0185: Synthesizing Equatable and Hashable conformance o SE-0184: Unsafe[Mutable][Raw][Buffer]Pointer: add missing methods, adjust existing labels for clarity, and remove deallocation size o SE-0157: Support recursive constraints on associated types o SE-0075: Adding a Build Configuration Import Test

• Implemented in Swift 4.0 o SE-0183: Substring performance affordances o SE-0182: String Newline Escaping o SE-0181: Package Manager C/C++ Language Standard Support o SE-0180: String Index Overhaul o SE-0179: Swift run Command o SE-0178: Add unicodeScalars property to Character o SE-0176: Enforce Exclusive Access to Memory o SE-0175: Package Manager Revised Dependency Resolution o SE-0173: Add MutableCollection.swapAt(::) o SE-0172: One-sided Ranges o SE-0171: Reduce with inout o SE-0170: NSNumber bridging and Numeric types o SE-0169: Improve Interaction Between private Declarations and Extensions o SE-0168: Multi-Line String Literals o SE-0167: Swift Encoders o SE-0166: Swift Archival & Serialization o SE-0165: Dictionary & Set Enhancements o SE-0164: Remove final support in protocol extensions o SE-0163: String Revision: Collection Conformance, C Interop, Transcoding o SE-0162: Package Manager Custom Target Layouts o SE-0161: Smart KeyPaths: Better Key-Value Coding for Swift o SE-0160: Limiting @objc inference o SE-0158: Package Manager Manifest API Redesign o SE-0156: Class and Subtype existentials o SE-0154: Provide Custom Collections for Dictionary Keys and Values o SE-0150: Package Manager Support for branches o SE-0149: Package Manager Support for Top of Tree development o SE-0148: Generic Subscripts o SE-0146: Package Manager Product Definitions o SE-0142: Permit where clauses to constrain associated types o SE-0104: Protocol-oriented integers

• Implemented in Swift 3.1 o SE-0152: Package Manager Tools Version o SE-0151: Package Manager Swift Language Compatibility Version o SE-0147: Move UnsafeMutablePointer.initialize(from:) to UnsafeMutableBufferPointer o SE-0145: Package Manager Version Pinning o SE-0141: Availability by Swift version o SE-0082: Package Manager Editable Packages o SE-0080: Failable Numeric Conversion Initializers o SE-0045: Add prefix(while:) and drop(while:) to the stdlib

• Implemented in Swift 3.0.1 o SE-0140: Warn when Optional converts to Any, and bridge Optional As Its Payload Or NSNull o SE-0139: Bridge Numeric Types to NSNumber and Cocoa Structs to NSValue o SE-0138: UnsafeRawBufferPointer

• Implemented in Swift 3.0 o SE-0155: Normalize Enum Case Representation o SE-0137: Avoiding Lock-In to Legacy Protocol Designs o SE-0136: Memory layout of values o SE-0135: Package Manager Support for Differentiating Packages by Swift version o SE-0134: Rename two UTF8-related properties on String o SE-0133: Rename flatten() to joined() o SE-0131: Add AnyHashable to the standard library o SE-0130: Replace repeating Character and UnicodeScalar forms of String.init o SE-0129: Package Manager Test Naming Conventions o SE-0128: Change failable UnicodeScalar initializers to failable o SE-0127: Clearing up stdlib Pointer and Buffer Routines o SE-0125: Remove NonObjectiveCBase and isUniquelyReferenced o SE-0124: Int.init(ObjectIdentifier) and UInt.init(ObjectIdentifier) should have a bitPattern: label o SE-0121: Remove Optional Comparison Operators o SE-0120: Revise partition Method Signature o SE-0118: Closure Parameter Names and Labels o SE-0117: Allow distinguishing between public access and public overridability o SE-0116: Import Objective-C id as Swift Any type o SE-0115: Rename Literal Syntax Protocols o SE-0114: Updating Buffer “Value” Names to “Header” Names o SE-0113: Add integral rounding functions to FloatingPoint o SE-0112: Improved NSError Bridging o SE-0111: Remove type system significance of function argument labels o SE-0109: Remove the Boolean protocol o SE-0107: UnsafeRawPointer API o SE-0106: Add a macOS Alias for the OSX Platform Configuration Test o SE-0103: Make non-escaping closures the default o SE-0102: Remove @noreturn attribute and introduce an empty Never type o SE-0101: Reconfiguring sizeof and related functions into a unified MemoryLayout struct o SE-0099: Restructuring Condition Clauses o SE-0096: Converting dynamicType from a property to an operator o SE-0095: Replace protocol<P1,P2> syntax with P1 & P2 syntax o SE-0094: Add sequence(first:next:) and sequence(state:next:) to the stdlib o SE-0093: Adding a public base property to slices o SE-0092: Typealiases in protocols and protocol extensions o SE-0091: Improving operator requirements in protocols o SE-0089: Renaming String.init(_:T) o SE-0088: Modernize libdispatch for Swift 3 naming conventions o SE-0086: Drop NS Prefix in Swift Foundation o SE-0085: Package Manager Command Names o SE-0081: Move where clause to end of declaration o SE-0077: Improved operator declarations o SE-0076: Add overrides taking an UnsafePointer source to non-destructive copying methods on UnsafeMutablePointer o SE-0072: Fully eliminate implicit bridging conversions from Swift o SE-0071: Allow (most) keywords in member references o SE-0070: Make Optional Requirements Objective-C-only o SE-0069: Mutability and Foundation Value Types o SE-0067: Enhanced Floating Point Protocols o SE-0066: Standardize function type argument syntax to require parentheses o SE-0065: A New Model for Collections and Indices o SE-0064: Referencing the Objective-C selector of property getters and setters o SE-0063: SwiftPM System Module Search Paths o SE-0062: Referencing Objective-C key-paths o SE-0061: Add Generic Result and Error Handling to autoreleasepool() o SE-0060: Enforcing order of Defaulted parameters o SE-0059: Update API Naming Guidelines and Rewrite Set APIs Accordingly o SE-0057: Importing Objective-C Lightweight Generics o SE-0055: Make unsafe pointer nullability explicit using Optional o SE-0053: Remove explicit use of let from Function Parameters o SE-0052: Change IteratorType post-nill guarantee o SE-0049: Move @noescape and @autoclosure to be type attributes o SE-0048: Generic Type Aliases o SE-0047: Defaulting non-Void functions so they warn on unused results o SE-0046: Establish consistent label behavior across all parameters including first labels o SE-0044: Import as member o SE-0043: Declare variables in ‘case’ labels with multiple patterns o SE-0040: Replacing Equal Signs with Colons For Attribute Arguments o SE-0039: Modernizing Playground Literals o SE-0038: Package Manager C Language Target Support o SE-0037: Clarify interaction between comments & operators o SE-0036: Requiring Leading Dot Prefixes for Enum Instance Member Implementations o SE-0035: Limiting inout capture to @noescape contexts o SE-0034: Disambiguating Line Control Statements from Debugging Identifiers o SE-0033: Import Objective-C Constants as Swift Types o SE-0032: Add first(where: ) method to Sequence o SE-0031: Adjusting inout Declarations for Type Decoration o SE-0029: Remove implicit tuple splat behavior from function applications o SE-0025: Scoped Access Level o SC-0023: API Design Guidelines o SE-0019: Swift Testing o SE-0017: Change Unmanaged to use UnsafePointer o SE-0016: Add initializers to Int and UInt to convert from UnsafePointer and UnsafeMutablePointer o SE-0008: Add a Lazy flatMap for Sequences of Optionals o SE-0007: Remove C-style for-loops with conditions and incrementers o SE-0006: Apply API Guidelines to the Standard Library o SE-0005: Better Translation of Objective-C APIs into Swift o SE-0004: Remove the ++ and – operators o SE-0003: Removing var from Function Parameters o SE-0002: Removing currying func declaration syntax

• Implemented in Swift 2.2 o SE-0028: Modernizing Swift’s Debugging Identifiers o SE-0022: Referencing the Objective-C selector of a method o SE-0021: Naming Functions with Argument Labels o SE-0020: Swift Language Version Build Configuration o SE-0015: Tuple comparison operators o SE-0014: Constraining AnySequence.init o SE-0011: Replace typealias keyword with associatedtype for associated type declarations o SE-0001: Allow (most) keywords as argument labels

amartini51 commented 8 months ago

This was considered when the Swift Evolution process started, and we intentionally didn't make this change at the time. I believe the main reason was that the average Swift developer isn't involved in the SE process and has no need to be aware of SE numbers — and those developers who do participate in reviews and read SE proposals already know which language versions include what changes.

That was several years ago, so perhaps we could revisit. To help that discussion, could you give a little more detail about why you think this information belongs in TSPL?

tadbyt commented 8 months ago

This document serves as the de facto language specification and is updated periodically as the language evolves. In the revision history section, changes to this document (The Swift Programming Language) are summarized, but changes to the language itself are limited to indicating the prior and current versions. There isn't, as far as I know, a ready manner to determine what the delta in the language is without crawling through SE's. Providing the titles of and links to the set of SE's that define those changes would provide a ready means for someone to skim through to determine whether the delta from one version of the language to another is material with respect to the features of the language that they utilize and provide them with a quick way to learn more. Swift is unlike many other languages, where one can readily access specifications for different (historical) versions of the language. Having such links in the revision history increases the likelihood that users of this document would also review the relevant SE's as each new release occurs and come up to speed more rapidly on the changes.

An alternative approach would be to simply provide this as a stand alone section, just prior to the revision history, titled something like Swift Language Evolution Synopsis.

One other thing to consider. The target audience for this document is not those involved with changing the language so much as those learning the language and practitioners whose use the document as a living reference work.

tadbyt commented 8 months ago

The attachments have links provided to the SE's.

Language Revision History.pdf

amartini51 commented 8 months ago

Information about which Swift Evolution proposals are implemented when is already available in the dashboard. We shouldn't try to manually replicate that in TSPL — the dashboard pulls the latest information live from the GitHub repository where Swift Evolution reviews happen.

amartini51 commented 7 months ago

The target audience for this document is not those involved with changing the language so much as those learning the language and practitioners whose use the document as a living reference work.

This is exactly the reason that I don't think discussion of SE proposals belongs in TSPL. Folks who want to participate in the evolution process already know where to find the proposals, and can look at the dashboard to see what was implemented when. Folks who aren't involved in evolution don't need care about SE proposals. Each revision history entry should tell you what new content content you should read, and what updated content you should re-read.

tadbyt commented 7 months ago

Perhaps I can suggest an alternative approach that would address both of our perspectives. Rather than include this in The Swift Programming Language, get agreement to provide it on the swift.org website, linked to by the Swift Evolution page. Each release identified in Document Revision History could then contain a link to the subsection of that page. This accomplishes providing a definition of what each release of the language entails as well as keeping the SE information consolidated on the swift.org website.

amartini51 commented 7 months ago

I agree that this information should be provided on Swift.org — in fact, that's where the dashboard I linked above is hosted today:

https://www.swift.org/swift-evolution/

If you haven't used this dashboard before, can I ask you to please take a look at it? It's also an open source project; you can suggest changes in that GitHub project. I believe this is the HTML file, which pulls in this JavaScript.

EDIT: If you're interested in a particular version of Swift, you need to open the filters by clicking the first button to the right of the search field. When you select "Implemented" you can choose a specific language version, and see what SE proposals were implemented in that version.

It's possible that we could add a see-also from the revision history to that dashboard, if an argument can be made that the average Swift developer has a reason to go there.

tadbyt commented 7 months ago

Another alternative that wouldn't require any changes to the Swift Evolution pages, would be to simply provide a link for each major releases (5..9, 5.8, 5.7, etc.) identified in the Revision History to the webpage listed in the Release column in the table under Goals and Release Notes on the page given below. Those pages provide the information to inform someone about what had changed in the language.

https://github.com/apple/swift-evolution#readme-ov-file

For 5.9, this would be https://www.swift.org/blog/swift-5.9-released/

tadbyt commented 7 months ago

Based on what is provided on https://www.swift.org/blog/ , the following is what is currently readily available to link to:

While that wouldn't cover all of the minor releases, it should be enough. Perhaps a note directing those interested to the Swift Evolution dashboard.

swiftlang / swift-book