diff --git a/process.md b/process.md index 754a5fdc7d..1af02f91a1 100644 --- a/process.md +++ b/process.md @@ -520,6 +520,35 @@ Review Manager +## Vision documents + +Like proposals, vision documents should generally not be renamed once they've been added to the repository. +It's okay to change the title in the text, but the filename should remain stable. + +Vision documents generally have fewer formatting guidelines to follow compared to proposal documents. +However, they should start with the following basic structure and use standard fields: + +```text +# Name of vision + +* Field1: value +* Field2: value + +The remainder of the document has no specific requirements. +``` + +Standard fields include: +* `Vision`: + exactly `[prefix-number](filename.md)`, where `prefix` is the appropriate document prefix (generally `SV` for all visions), + `number` is the sequence number of this vision within that prefix, and `filename.md` is the filename of this vision document. + Required in all vision documents. +* `Proposal`: + a comma-separated list of links to proposal documents which are related to this vision. + This field is typically not used when a vision is first written, since there are no related proposals + for it yet, but it may be added retrospectively. Optional. + +These standard fields should be provided in this order. + [forums]: https://forums.swift.org/ diff --git a/visions/0001-using-swift-from-c++.md b/visions/0001-using-swift-from-c++.md new file mode 100644 index 0000000000..f8e3db6847 --- /dev/null +++ b/visions/0001-using-swift-from-c++.md @@ -0,0 +1,10 @@ +# Using Swift from C++ + +* Vision: [SV-0001](using-swift-from-c++.md) + +> [!NOTE] +> This file exists only to reserve vision ID 0001. The `visions/` directory did +> not originally use numbered identifiers; this ID was assigned retroactively +> when numbering was introduced later on. The original document, which predates +> versioning, can be found at +> [`visions/using-swift-from-c++.md`](using-swift-from-c++.md). diff --git a/visions/0002-macros.md b/visions/0002-macros.md new file mode 100644 index 0000000000..75688d3395 --- /dev/null +++ b/visions/0002-macros.md @@ -0,0 +1,9 @@ +# A Vision for Macros in Swift + +* Vision: [SV-0002](macros.md) + +> [!NOTE] +> This file exists only to reserve vision ID 0002. The `visions/` directory did +> not originally use numbered identifiers; this ID was assigned retroactively +> when numbering was introduced later on. The original document, which predates +> versioning, can be found at [`visions/macros.md`](macros.md). diff --git a/visions/0003-using-c++-from-swift.md b/visions/0003-using-c++-from-swift.md new file mode 100644 index 0000000000..b334331f87 --- /dev/null +++ b/visions/0003-using-c++-from-swift.md @@ -0,0 +1,10 @@ +# Using C++ from Swift + +* Vision: [SV-0003](using-c++-from-swift.md) + +> [!NOTE] +> This file exists only to reserve vision ID 0003. The `visions/` directory did +> not originally use numbered identifiers; this ID was assigned retroactively +> when numbering was introduced later on. The original document, which predates +> versioning, can be found at +> [`visions/using-c++-from-swift.md`](using-c++-from-swift.md). diff --git a/visions/0004-embedded-swift.md b/visions/0004-embedded-swift.md new file mode 100644 index 0000000000..36cc4d7849 --- /dev/null +++ b/visions/0004-embedded-swift.md @@ -0,0 +1,9 @@ +# A Vision for Embedded Swift + +* Vision: [SV-0004](embedded-swift.md) + +> [!NOTE] +> This file exists only to reserve vision ID 0004. The `visions/` directory did +> not originally use numbered identifiers; this ID was assigned retroactively +> when numbering was introduced later on. The original document, which predates +> versioning, can be found at [`visions/embedded-swift.md`](embedded-swift.md). diff --git a/visions/0005-webassembly.md b/visions/0005-webassembly.md new file mode 100644 index 0000000000..7e4bd47c99 --- /dev/null +++ b/visions/0005-webassembly.md @@ -0,0 +1,9 @@ +# A Vision for WebAssembly Support in Swift + +* Vision: [SV-0005](webassembly.md) + +> [!NOTE] +> This file exists only to reserve vision ID 0005. The `visions/` directory did +> not originally use numbered identifiers; this ID was assigned retroactively +> when numbering was introduced later on. The original document, which predates +> versioning, can be found at [`visions/webassembly.md`](webassembly.md). diff --git a/visions/0006-swift-testing.md b/visions/0006-swift-testing.md new file mode 100644 index 0000000000..87d528addf --- /dev/null +++ b/visions/0006-swift-testing.md @@ -0,0 +1,9 @@ +# A New Direction for Testing in Swift + +* Vision: [SV-0006](swift-testing.md) + +> [!NOTE] +> This file exists only to reserve vision ID 0006. The `visions/` directory did +> not originally use numbered identifiers; this ID was assigned retroactively +> when numbering was introduced later on. The original document, which predates +> versioning, can be found at [`visions/swift-testing.md`](swift-testing.md). diff --git a/visions/0007-memory-safety.md b/visions/0007-memory-safety.md new file mode 100644 index 0000000000..379bc651cd --- /dev/null +++ b/visions/0007-memory-safety.md @@ -0,0 +1,9 @@ +# Optional Strict Memory Safety for Swift + +* Vision: [SV-0007](memory-safety.md) + +> [!NOTE] +> This file exists only to reserve vision ID 0007. The `visions/` directory did +> not originally use numbered identifiers; this ID was assigned retroactively +> when numbering was introduced later on. The original document, which predates +> versioning, can be found at [`visions/memory-safety.md`](memory-safety.md). diff --git a/visions/0008-approachable-concurrency.md b/visions/0008-approachable-concurrency.md new file mode 100644 index 0000000000..89fc0f1472 --- /dev/null +++ b/visions/0008-approachable-concurrency.md @@ -0,0 +1,10 @@ +# Improving the approachability of data-race safety + +* Vision: [SV-0008](approachable-concurrency.md) + +> [!NOTE] +> This file exists only to reserve vision ID 0008. The `visions/` directory did +> not originally use numbered identifiers; this ID was assigned retroactively +> when numbering was introduced later on. The original document, which predates +> versioning, can be found at +> [`visions/approachable-concurrency.md`](approachable-concurrency.md). diff --git a/visions/0009-networking.md b/visions/0009-networking.md new file mode 100644 index 0000000000..827b825c7c --- /dev/null +++ b/visions/0009-networking.md @@ -0,0 +1,9 @@ +# A Vision for Networking in Swift + +* Vision: [SV-0009](networking.md) + +> [!NOTE] +> This file exists only to reserve vision ID 0009. The `visions/` directory did +> not originally use numbered identifiers; this ID was assigned retroactively +> when numbering was introduced later on. The original document, which predates +> versioning, can be found at [`visions/networking.md`](networking.md). diff --git a/visions/approachable-concurrency.md b/visions/approachable-concurrency.md index 25e6e6b725..c525117771 100644 --- a/visions/approachable-concurrency.md +++ b/visions/approachable-concurrency.md @@ -1,6 +1,7 @@ # Improving the approachability of data-race safety -[SE-0434]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0434-global-actor-isolated-types-usability.md +* Vision: [SV-0008](approachable-concurrency.md) +* Proposal: [SE-0434]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0434-global-actor-isolated-types-usability.md > This document is an official feature [vision document](https://forums.swift.org/t/the-role-of-vision-documents-in-swift-evolution/62101). The Language Steering Group has endorsed the goals and basic approach laid out in this document. This endorsement is not a pre-approval of any of the concrete proposals that may come out of this document. All proposals will undergo normal evolution review, which may result in rejection or revision from how they appear in this document. diff --git a/visions/embedded-swift.md b/visions/embedded-swift.md index 7bd8d7aa50..0eea74c03d 100644 --- a/visions/embedded-swift.md +++ b/visions/embedded-swift.md @@ -1,5 +1,7 @@ # A Vision for Embedded Swift +* Vision: [SV-0004](embedded-swift.md) + ## Introduction Swift is a general purpose programming language suitable for both high-level application software and for low-level systems software. The existing major supported deployments of Swift are primarily targeting “large” operating systems (Linux, Windows, macOS, iOS), where storage and memory are relatively plentiful, multiple applications share code via dynamic linking, and the system can be expected to provide a number of common libraries (such as the C and C++ standard libraries). The typical size of the Swift runtime and standard library in these environments is around 5MB of binary size. diff --git a/visions/macros.md b/visions/macros.md index 90917903c9..ea1a870b8f 100644 --- a/visions/macros.md +++ b/visions/macros.md @@ -1,5 +1,7 @@ # A Vision for Macros in Swift +* Vision: [SV-0002](macros.md) + As Swift evolves, it gains new language features and capabilities. There are different categories of features: some fill in gaps, taking existing syntax that is not permitted and giving it a semantics that fit well with the existing language, for example conditional conformance or allowing existential values for protocols with `Self` or associated type requirements. Others introduce new capabilities or paradigms to the language, such as the addition of concurrency, ownership types, or comprehensive reflection. There is another large category of language features that provide syntactic sugar to eliminate common boilerplate, taking something that can be written out in long-form and making it more concise. Such features don't technically add any expressive power to the language, because you can always write the long-form version, but their effect can be transformational if it enables use cases that would otherwise have been unwieldy. The synthesis of `Codable` conformances, for example, is sheer boilerplate reduction, but it makes `Codable` support ubiquitous throughout the Swift ecosystem. Property wrappers allow one to factor out logic for property access, and have enabled a breadth of powerful libraries. New language features in this category are hard to evaluate, because there is a fundamental question of whether the feature is "worth it": does the set of use cases made better by this feature outweigh the cost of making the language larger and more complicated? diff --git a/visions/memory-safety.md b/visions/memory-safety.md index 69a206bc79..70fc5a98f2 100644 --- a/visions/memory-safety.md +++ b/visions/memory-safety.md @@ -1,5 +1,7 @@ # Optional Strict Memory Safety for Swift +* Vision: [SV-0007](memory-safety.md) + Swift is a memory-safe language *by default* , meaning that the major language features and standard library APIs are memory-safe. However, it is possible to opt out of memory safety when it’s pragmatic using certain “unsafe” language or library constructs. This document proposes a path toward an optional “strict” subset of Swift that prohibits any unsafe features. This subset is intended to be used for Swift code bases where memory safety is an absolute requirement, such as security-critical libraries. This document is an official feature [vision document](https://forums.swift.org/t/the-role-of-vision-documents-in-swift-evolution/62101). The Language Steering Group has endorsed the goals and basic approach laid out in this document. This endorsement is not a pre-approval of any of the concrete proposals that may come out of this document. All proposals will undergo normal evolution review, which may result in rejection or revision from how they appear in this document. diff --git a/visions/networking.md b/visions/networking.md index 4b6e69df89..f802a36015 100644 --- a/visions/networking.md +++ b/visions/networking.md @@ -1,5 +1,7 @@ # A Vision for Networking in Swift +* Vision: [SV-0009](networking.md) + ## Introduction Almost every Swift application touches a network, yet Swift developers face a fragmented landscape of overlapping solutions with no clear guidance on which to choose. diff --git a/visions/swift-testing.md b/visions/swift-testing.md index 5133114e93..34bb234591 100644 --- a/visions/swift-testing.md +++ b/visions/swift-testing.md @@ -1,5 +1,7 @@ # A New Direction for Testing in Swift +* Vision: [SV-0006](swift-testing.md) + ## Introduction A key requirement for the success of any developer platform is a way to use diff --git a/visions/using-c++-from-swift.md b/visions/using-c++-from-swift.md index 4b43b13acc..0cd9ec92f0 100644 --- a/visions/using-c++-from-swift.md +++ b/visions/using-c++-from-swift.md @@ -1,5 +1,7 @@ # Using C++ from Swift +* Vision: [SV-0003](using-c++-from-swift.md) + ## Introduction This document lays out a vision for the development of the "forward" half of C++ and Swift interoperability: using C++ APIs from Swift. It sets overarching goals that drive the project’s design decisions, outlines some high-level topics related to C++ interoperability, and, finally, investigates a collection of specific API patterns and potential ways for the compiler to import them. This vision is a sketch, rather than a final design for C++ and Swift interoperability. Towards the end, this document suggests a process for evolving C++ interoperability over time, and it lays out the path for finalizing the designs discussed here. diff --git a/visions/using-swift-from-c++.md b/visions/using-swift-from-c++.md index 65583f2ec5..d84829caa7 100644 --- a/visions/using-swift-from-c++.md +++ b/visions/using-swift-from-c++.md @@ -1,5 +1,7 @@ # Using Swift from C++ +* Vision: [SV-0001](using-swift-from-c++.md) + This vision document presents a high level overview of the "reverse" (i.e. Swift-to-C++) half of the C++ interoperability Swift language feature. It highlights the key principles and goals that determine how Swift APIs are exposed to C++ users. It also outlines the evolution process for this feature. This document does not present the final design for how Swift APIs get mapped to C++ language constructs. The final design of this feature will evolve as this feature goes through the Swift evolution process. This document does not cover the "forward" (i.e. using C++ APIs from Swift) aspect of the C++ interoperability, as it’s covered by a [sibling document](https://github.com/apple/swift/pull/60501/files). This document is an official feature vision document, as described in the [draft review management guidelines](https://github.com/rjmccall/swift-evolution/blob/057b2383102f34c3d0f5b257f82bba0f5b94683d/review_management.md#future-directions-and-roadmaps) of the Swift evolution process. The Language Workgroup has endorsed the goals and basic approach laid out in this document. This endorsement is not a pre-approval of any of the concrete proposals that may come out of this document. All proposals will undergo normal evolution review, which may result in rejection or revision from how they appear in this document. diff --git a/visions/webassembly.md b/visions/webassembly.md index 95aa29f884..5f29d151ba 100644 --- a/visions/webassembly.md +++ b/visions/webassembly.md @@ -1,5 +1,7 @@ # A Vision for WebAssembly Support in Swift +* Vision: [SV-0005](webassembly.md) + ## Introduction WebAssembly (abbreviated [Wasm](https://webassembly.github.io/spec/core/intro/introduction.html#wasm)) is a virtual