diff --git a/docs/ABIStabilityManifesto.md b/docs/ABIStabilityManifesto.md
index 364acf93b1b0e..b3ece2d52e1aa 100644
--- a/docs/ABIStabilityManifesto.md
+++ b/docs/ABIStabilityManifesto.md
@@ -18,7 +18,7 @@ One of the top priorities for Swift right now is compatibility across future Swi
This document is an exploration and explanation of Swift's ABI alongside the goals and investigations needed before declaring Swift's ABI stable. It is meant to be a resource to the community as well as a declaration of the direction of Swift's ABI.
-Throughout this document there will be references to issues in Swift's [issue tracking system](https://bugs.swift.org) denoted by "SR-xxxx". These references track open engineering and design tasks for Swift's ABI.
+Throughout this document there will be references to GitHub issues denoted by `#`. These references track open engineering and design tasks for Swift's ABI.
### What Is ABI?
@@ -106,7 +106,7 @@ Opaque layout occurs whenever the layout is not known until runtime. This can co
The size and alignment of an object of opaque layout, as well as whether it is trivial or bitwise movable, is determined by querying its value witness table, which is described further in the [value witness table section](#value-witness-table). The offsets for data members are determined by querying the type's metadata, which is described further in the [value metadata section](#value-metadata). Objects of opaque layout must typically be passed indirectly, described further in the [function signature lowering section](#function-signature-lowering). The Swift runtime interacts with objects of opaque layout through pointers, and thus they must be addressable, described further in the [abstraction levels section](#abstraction-levels).
-In practice, layout might be partially-known at compilation time. An example is a generic struct over type `T` that stores an integer as well as an object of type `T`. In this case, the layout of the integer itself is known and its location within the generic struct might be as well, depending on the specifics of the layout algorithm. However, the generic stored property has opaque layout, and thus the struct overall has an unknown size and alignment. We are investigating how to most efficiently lay out partially-opaque aggregates [[SR-3722](https://bugs.swift.org/browse/SR-3722)]. This will likely entail placing the opaque members at the end in order to guarantee known offsets of non-opaque data members.
+In practice, layout might be partially-known at compilation time. An example is a generic struct over type `T` that stores an integer as well as an object of type `T`. In this case, the layout of the integer itself is known and its location within the generic struct might be as well, depending on the specifics of the layout algorithm. However, the generic stored property has opaque layout, and thus the struct overall has an unknown size and alignment. We are investigating how to most efficiently lay out partially-opaque aggregates [[#46307](https://github.com/apple/swift/issues/46307)]. This will likely entail placing the opaque members at the end in order to guarantee known offsets of non-opaque data members.
#### Library Evolution
@@ -116,7 +116,7 @@ In order to allow for cross-module optimizations for modules that are distribute
Resilient types are required to have opaque layout when exposed outside their resilience domain. Inside a resilience domain, this requirement is lifted and their layout may be statically known or opaque as determined by their type (see [previous section](#opaque-layout)).
-Annotations may be applied to a library's types in future versions of that library, in which case the annotations are versioned, yet the library remains binary compatible. How this will impact the ABI is still under investigation [[SR-3911](https://bugs.swift.org/browse/SR-3911)].
+Annotations may be applied to a library's types in future versions of that library, in which case the annotations are versioned, yet the library remains binary compatible. How this will impact the ABI is still under investigation [[#46496](https://github.com/apple/swift/issues/46496)].
#### Abstraction Levels
@@ -132,9 +132,9 @@ What follows is a breakdown of the different kinds of types in Swift and what ne
#### Structs
-The layout algorithm for structs should result in an efficient use of space, possibly by laying out fields in a different order than declared [[SR-3723](https://bugs.swift.org/browse/SR-3723)]. We may want a fully declaration-order-agnostic algorithm to allow data members to be reordered in source without breaking binary compatibility [[SR-3724](https://bugs.swift.org/browse/SR-3724)]. We also need to consider whether, by default, we want to ensure struct data members are addressable (i.e. byte-aligned) or if we'd rather do bit-packing to save space [[SR-3725](https://bugs.swift.org/browse/SR-3725)].
+The layout algorithm for structs should result in an efficient use of space, possibly by laying out fields in a different order than declared [[#46308](https://github.com/apple/swift/issues/46308)]. We may want a fully declaration-order-agnostic algorithm to allow data members to be reordered in source without breaking binary compatibility [[#46309](https://github.com/apple/swift/issues/46309)]. We also need to consider whether, by default, we want to ensure struct data members are addressable (i.e. byte-aligned) or if we'd rather do bit-packing to save space [[#46310](https://github.com/apple/swift/issues/46310)].
-Zero sized structs do not take up any space as data members and struct members may be laid out in the padding of sub-structs. We may want to explore whether there are implementation benefits to capping alignment at some number, e.g. 16 on many platforms [[SR-3912](https://bugs.swift.org/browse/SR-3912)].
+Zero sized structs do not take up any space as data members and struct members may be laid out in the padding of sub-structs. We may want to explore whether there are implementation benefits to capping alignment at some number, e.g. 16 on many platforms [[#46497](https://github.com/apple/swift/issues/46497)].
#### Tuples
@@ -142,7 +142,7 @@ Tuples are similar to anonymous structs, but they differ in that they exhibit st
This may be an argument for a simple, declaration-order, non bit-packed layout algorithm for tuples. Tuples are often used for small local values and rarely persisted across ABI boundaries in a way that aggressive packing is performance-critical. This would also be more consistent with how fixed-size C arrays are presented in Swift, which are imported as tuples.
-We should investigate whether to aggressively bit-pack tuple elements similarly to structs, paying the reabstraction costs, or if the benefits are not worth the costs [[SR-3726](https://bugs.swift.org/browse/SR-3726)].
+We should investigate whether to aggressively bit-pack tuple elements similarly to structs, paying the reabstraction costs, or if the benefits are not worth the costs [[#46311](https://github.com/apple/swift/issues/46311)].
Tuples should be binary compatible between labeled and unlabeled tuples of the same type and structure.
@@ -161,7 +161,7 @@ Degenerate enums take zero space. Trivial enums are just their discriminator.
Single payload enums try to fit their discriminator in the payload's extra inhabitants for the non-payload cases, otherwise they will store the discriminator after the payload. When the discriminator is stored after the payload, the bits are not set for the payload case. The payload is guaranteed to be layout compatible with the enum as the payload case does not use any extra inhabitants. Storing the discriminator after the payload may also result in more efficient layout of aggregates containing the enum, due to alignment.
-The layout algorithm for multi-payload enums is more complicated and still needs to be developed [[SR-3727](https://bugs.swift.org/browse/SR-3727)]. The algorithm should try to rearrange payloads so as to coalesce cases and save space. This rearrangement can also improve performance and code size. For example, if ARC-ed payload components reside in the same location, operations like copy can be done directly on the values without extensive switching.
+The layout algorithm for multi-payload enums is more complicated and still needs to be developed [[#46312](https://github.com/apple/swift/issues/46312)]. The algorithm should try to rearrange payloads so as to coalesce cases and save space. This rearrangement can also improve performance and code size. For example, if ARC-ed payload components reside in the same location, operations like copy can be done directly on the values without extensive switching.
Enum raw values are not ABI, as they are implemented as code present in the computed property getter and setter. `@objc` enums are C-compatible, which means they must be trivial.
@@ -177,7 +177,7 @@ The layout of class instances is mostly opaque. This is to avoid the vexing prob
The run-time type of a non-final class instance or a class existential is not known statically. To facilitate dynamic casts, the object must store a pointer to its type, called the *isa* pointer. The *isa* pointer is always stored at offset 0 within the object. How that type is represented and what information it provides is part of the class's metadata and is covered in the [class metadata section](#class-metadata). Similarly, the function for a non-final method call is also not known statically and is dispatched based on the run-time type. Method dispatch is covered in the [method dispatch section](#method-dispatch).
-Class instances will, as part of ABI-stability, guarantee a word-sized field of opaque data following the isa field that may be used for reference counting by the runtime [[SR-4353](https://bugs.swift.org/browse/SR-4353)]. But, the format and conventions of this opaque data will not be ABI at first in order to have more flexibility for language or implementation changes. Instead, runtime functions provide the means to interact with reference counts. This opaque data and its conventions may be locked down for more efficient access in the future, which will be an ABI-additive change.
+Class instances will, as part of ABI-stability, guarantee a word-sized field of opaque data following the isa field that may be used for reference counting by the runtime [[#46932](https://github.com/apple/swift/issues/46932)]. But, the format and conventions of this opaque data will not be ABI at first in order to have more flexibility for language or implementation changes. Instead, runtime functions provide the means to interact with reference counts. This opaque data and its conventions may be locked down for more efficient access in the future, which will be an ABI-additive change.
##### References
@@ -187,7 +187,7 @@ References to Objective-C-compatible class instances (i.e. those that inherit fr
References to native, non-Objective-C-compatible Swift class instances do not have this constraint. The alignment of native Swift class instances is part of ABI, providing spare bits in the lower bits of references. Platforms may also provide spare bits (typically upper bits) and extra inhabitants (typically lower addresses) for references due to limited address spaces.
-We may want to explore using spare bits in references to store local reference counts in order to perform some ARC operations more efficiently [[SR-3728](https://bugs.swift.org/browse/SR-3728)]. These would need to be flushed to the object whenever a reference may escape or the local reference count reaches zero. If these local reference counts can cross ABI boundaries, then such a change will have to be implemented in an ABI-additive way with deployment target checking.
+We may want to explore using spare bits in references to store local reference counts in order to perform some ARC operations more efficiently [[#46313](https://github.com/apple/swift/issues/46313)]. These would need to be flushed to the object whenever a reference may escape or the local reference count reaches zero. If these local reference counts can cross ABI boundaries, then such a change will have to be implemented in an ABI-additive way with deployment target checking.
#### Existential Containers
@@ -205,11 +205,11 @@ A type's conformance to a protocol consists of functions (whether methods or get
Class-constrained existentials omit the metadata pointer (as the object itself contains a pointer to its type), as well as any excess inline buffer space. `Any`, which is an existential value without any conformances, has no witness table pointer.
-We are re-evaluating the inline buffer size for existential containers prior to ABI stability [[SR-3340](https://bugs.swift.org/browse/SR-3340)]. We are also considering making the out-of-line allocation be copy-on-write (COW) [[SR-4330](https://bugs.swift.org/browse/SR-4330)]. We should also explore "exploding" existential parameters, i.e. converting an existential parameter into a protocol-constrained generic parameter [[SR-4331](https://bugs.swift.org/browse/SR-4331)].
+We are re-evaluating the inline buffer size for existential containers prior to ABI stability [[#45928](https://github.com/apple/swift/issues/45928)]. We are also considering making the out-of-line allocation be copy-on-write (COW) [[#46913](https://github.com/apple/swift/issues/46913)]. We should also explore "exploding" existential parameters, i.e. converting an existential parameter into a protocol-constrained generic parameter [[#46914](https://github.com/apple/swift/issues/46914)].
### Declaring Stability
-ABI stability means nailing down type layout and making decisions about how to handle the concerns of Library Evolution. The end result will be a technical specification of the layout algorithms that future compilers must adhere to in order to ensure binary compatibility [[SR-3730](https://bugs.swift.org/browse/SR-3730)].
+ABI stability means nailing down type layout and making decisions about how to handle the concerns of Library Evolution. The end result will be a technical specification of the layout algorithms that future compilers must adhere to in order to ensure binary compatibility [[#46315](https://github.com/apple/swift/issues/46315)].
For all of the areas discussed above, more aggressive layout improvements may be invented in the post-ABI stability future. For example, we may want to explore rearranging and packing nested type data members with outer type data members. Such improvements would have to be done in an ABI-additive fashion through deployment target and/or min-version checking. This may mean that the module file will need to track per-type ABI versioning information.
@@ -222,13 +222,13 @@ While data layout specifies the layout of objects of a given type, *type metadat
Swift keeps metadata records for every *concrete type*. Concrete types include all non-generic types as well as generic types with concrete type parameters. These records are created by the compiler as well as lazily created at run time (e.g. for generic type instantiations). This metadata stores information about its type, discussed in each section below.
-A potential approach to stability mechanism is to provide metadata read/write functions alongside the runtime to interact with metadata, giving some freedom to the underlying structures to grow and change. This effectively makes large portions of metadata opaque. But, certain fields require access to be as efficient as possible (e.g. dynamic casts, calling into witness tables) and the performance hit from going through an intermediary function would be unacceptable. Thus, we will probably freeze the performance-critical parts and use accessor functions for the rest [[SR-3923](https://bugs.swift.org/browse/SR-3923)].
+A potential approach to stability mechanism is to provide metadata read/write functions alongside the runtime to interact with metadata, giving some freedom to the underlying structures to grow and change. This effectively makes large portions of metadata opaque. But, certain fields require access to be as efficient as possible (e.g. dynamic casts, calling into witness tables) and the performance hit from going through an intermediary function would be unacceptable. Thus, we will probably freeze the performance-critical parts and use accessor functions for the rest [[#46508](https://github.com/apple/swift/issues/46508)].
-Metadata has many historical artifacts in its representation that we want to clean up [[SR-3924](https://bugs.swift.org/browse/SR-3924)]. We also want to make small tweaks to present more semantic information in the metadata, to enable better future tooling and features such as reflection [[SR-3925](https://bugs.swift.org/browse/SR-3925)]. Some of these need to be done before declaring ABI stability and some may be additive.
+Metadata has many historical artifacts in its representation that we want to clean up [[#46509](https://github.com/apple/swift/issues/46509)]. We also want to make small tweaks to present more semantic information in the metadata, to enable better future tooling and features such as reflection [[#46510](https://github.com/apple/swift/issues/46510)]. Some of these need to be done before declaring ABI stability and some may be additive.
#### Declaring Stability
-Stabilizing the ABI means producing a precise technical specification for the fixed part of the metadata layout of all language constructs so that future compilers and tools can continue to read and write them. A prose description is not necessarily needed, though explanations are useful. We will also want to carve out extra space for areas where it is likely to be needed for future functionality [[SR-3731](https://bugs.swift.org/browse/SR-3731)].
+Stabilizing the ABI means producing a precise technical specification for the fixed part of the metadata layout of all language constructs so that future compilers and tools can continue to read and write them. A prose description is not necessarily needed, though explanations are useful. We will also want to carve out extra space for areas where it is likely to be needed for future functionality [[#46316](https://github.com/apple/swift/issues/46316)].
For more, but potentially out of date, details see the [Type Metadata docs](https://github.com/apple/swift/blob/main/docs/ABI/TypeMetadata.rst).
@@ -240,7 +240,7 @@ At run time, objects only have concrete types. If the type in source code is gen
### Value Metadata
-Named value types store the type name (currently mangled but we are investigating un-mangled [[SR-3926](https://bugs.swift.org/browse/SR-3926)]) and a pointer to the type's parent for nested types.
+Named value types store the type name (currently mangled but we are investigating un-mangled [[#46511](https://github.com/apple/swift/issues/46511)]) and a pointer to the type's parent for nested types.
Value type metadata also has kind-specific entries. Struct metadata stores information about its fields, field offsets, field names, and field metadata. Enum metadata stores information about its cases, payload sizes, and payload metadata. Tuple metadata stores information about its elements and labels.
@@ -248,21 +248,21 @@ Value type metadata also has kind-specific entries. Struct metadata stores infor
Every concrete type has a *value witness table* that provides information about how to lay out and manipulate values of that type. When a value type has [opaque layout](#opaque-layout), the actual layout and properties of that value type are not known at compilation time, so the value witness table is consulted.
-The value witness table stores whether a type is trivial and/or bitwise movable, whether there are extra inhabitants and if so how to store and retrieve them, etc. For enums, the value witness table will also provide functionality for interacting with the discriminator. There may be more efficient ways of representing enums that simplify this functionality (or provide a fast path), and that's under investigation [[SR-4332](https://bugs.swift.org/browse/SR-4332)].
+The value witness table stores whether a type is trivial and/or bitwise movable, whether there are extra inhabitants and if so how to store and retrieve them, etc. For enums, the value witness table will also provide functionality for interacting with the discriminator. There may be more efficient ways of representing enums that simplify this functionality (or provide a fast path), and that's under investigation [[#46915](https://github.com/apple/swift/issues/46915)].
-These value witness tables may be constructed statically for known values or dynamically for some generic values. While every unique type in Swift has a unique metadata pointer, value witness tables can be shared by types so long as the information provided is identical (i.e. same layout). Value witness tables always represent a type at its highest [abstraction level](#abstraction-levels). The value witness table entries and structure need to be locked down for ABI stability [[SR-3927](https://bugs.swift.org/browse/SR-3927)].
+These value witness tables may be constructed statically for known values or dynamically for some generic values. While every unique type in Swift has a unique metadata pointer, value witness tables can be shared by types so long as the information provided is identical (i.e. same layout). Value witness tables always represent a type at its highest [abstraction level](#abstraction-levels). The value witness table entries and structure need to be locked down for ABI stability [[#46512](https://github.com/apple/swift/issues/46512)].
### Class Metadata
Swift class metadata is layout-compatible with Objective-C class objects on Apple's platforms, which places requirements on the contents of the first section of class metadata. In this first section, entries such as super class pointers, instance size, instance alignment, flags, and opaque data for the Objective-C runtime are stored.
-Following that are superclass members, parent type metadata, generic parameter metadata, class members, and *vtables*, described below. Library evolution may present many changes to what exactly is present and will likely make many of the contents opaque to accommodate changes [[SR-4343](https://bugs.swift.org/browse/SR-4343)].
+Following that are superclass members, parent type metadata, generic parameter metadata, class members, and *vtables*, described below. Library evolution may present many changes to what exactly is present and will likely make many of the contents opaque to accommodate changes [[#46922](https://github.com/apple/swift/issues/46922)].
##### Method Dispatch
Invoking a non-final instance method involves calling a function that is not known at compile time: it must be resolved at run time. This is solved through the use of a *vtable*, or virtual method table (so called because overridable methods are also known as "virtual" methods). A *vtable* is a table of function pointers to a class or subclass's implementation of overridable methods. If the vtable is determined to be part of ABI, it needs a layout algorithm that also provides flexibility for library evolution.
-Alternatively, we may decide to perform inter-module calls through opaque *thunks*, or compiler-created intermediary functions, which then perform either direct or vtable dispatch as needed [[SR-3928](https://bugs.swift.org/browse/SR-3928)]. This enables greater library evolution without breaking binary compatibility by allowing internal class hierarchies to change. This would also unify non-final method dispatch between open and non-open classes while still allowing for aggressive compiler optimizations like de-virtualization for non-open classes. This approach would make vtables not be ABI, as that part of the type metadata would effectively be opaque to another module.
+Alternatively, we may decide to perform inter-module calls through opaque *thunks*, or compiler-created intermediary functions, which then perform either direct or vtable dispatch as needed [[#46513](https://github.com/apple/swift/issues/46513)]. This enables greater library evolution without breaking binary compatibility by allowing internal class hierarchies to change. This would also unify non-final method dispatch between open and non-open classes while still allowing for aggressive compiler optimizations like de-virtualization for non-open classes. This approach would make vtables not be ABI, as that part of the type metadata would effectively be opaque to another module.
### Protocol and Existential Metadata
@@ -270,15 +270,15 @@ Alternatively, we may decide to perform inter-module calls through opaque *thunk
The protocol witness table is a function table of a type's conformance to the protocol's interfaces. If the protocol also has an associated type requirement, then the witness table will store the metadata for the associated type. Protocol witness tables are used with [existential containers](#existential-containers) where the run time type is not known.
-Protocol witness tables may be created dynamically by the runtime or statically by the compiler. The layout of a protocol witness table is ABI and we need to determine a layout algorithm that also accommodates library evolution concerns, where additional protocol requirements may be added with default fall-backs [[SR-3732](https://bugs.swift.org/browse/SR-3732)].
+Protocol witness tables may be created dynamically by the runtime or statically by the compiler. The layout of a protocol witness table is ABI and we need to determine a layout algorithm that also accommodates library evolution concerns, where additional protocol requirements may be added with default fall-backs [[#46317](https://github.com/apple/swift/issues/46317)].
##### Existential Metadata
-Existential type metadata contains the number of witness tables present, whether the type is class-constrained, and a *protocol descriptor* for each protocol constraint. A protocol descriptor describes an individual protocol constraint, such as whether it is class-constrained, the size of conforming witness tables, and protocol descriptors for any protocols it refines. Protocol descriptors are layout compatible with the Objective-C runtime's protocol records on Apple platforms. The format of the existential type metadata needs to be reviewed as part of the ABI definition [[SR-4341](https://bugs.swift.org/browse/SR-4341)].
+Existential type metadata contains the number of witness tables present, whether the type is class-constrained, and a *protocol descriptor* for each protocol constraint. A protocol descriptor describes an individual protocol constraint, such as whether it is class-constrained, the size of conforming witness tables, and protocol descriptors for any protocols it refines. Protocol descriptors are layout compatible with the Objective-C runtime's protocol records on Apple platforms. The format of the existential type metadata needs to be reviewed as part of the ABI definition [[#46920](https://github.com/apple/swift/issues/46920)].
### Function Metadata
-In addition to common metadata entries, function type metadata stores information about the function signature: parameter and result type metadata, calling convention, per-parameter ownership conventions, and whether the function throws. Function type metadata always represents the function at its highest abstraction level, which is explained later in the [function signature lowering section](#lowering-higher-order-functions). Function parameters are currently modeled with a tuple-based design, but this should be updated to match modern Swift [[SR-4333](https://bugs.swift.org/browse/SR-4333)]. As more ownership semantics are modeled, more information may be stored about each parameter.
+In addition to common metadata entries, function type metadata stores information about the function signature: parameter and result type metadata, calling convention, per-parameter ownership conventions, and whether the function throws. Function type metadata always represents the function at its highest abstraction level, which is explained later in the [function signature lowering section](#lowering-higher-order-functions). Function parameters are currently modeled with a tuple-based design, but this should be updated to match modern Swift [[#46916](https://github.com/apple/swift/issues/46916)]. As more ownership semantics are modeled, more information may be stored about each parameter.
## Mangling
@@ -286,7 +286,7 @@ Mangling is used to produce unique symbols. It applies to both external (public)
ABI stability means a stable mangling scheme, fully specified so that future compilers and tools can honor it. For a potentially out-of-date specification of what the mangling currently looks like, see the [Name Mangling docs](https://github.com/apple/swift/blob/main/docs/ABI/Mangling.rst).
-There are some corner cases currently in the mangling scheme that should be fixed before declaring ABI stability. We need to come up with a canonicalization of generic and protocol requirements to allow for order-agnostic mangling [[SR-3733](https://bugs.swift.org/browse/SR-3733)]. We also may decide to more carefully mangle variadicity of function parameters, etc [[SR-3734](https://bugs.swift.org/browse/SR-3734)]. Most often, though, mangling improvements focus on reducing symbol size.
+There are some corner cases currently in the mangling scheme that should be fixed before declaring ABI stability. We need to come up with a canonicalization of generic and protocol requirements to allow for order-agnostic mangling [[#46318](https://github.com/apple/swift/issues/46318)]. We also may decide to more carefully mangle variadicity of function parameters, etc [[#46319](https://github.com/apple/swift/issues/46319)]. Most often, though, mangling improvements focus on reducing symbol size.
Mangling design centers around coming up with short and efficient manglings that still retain important properties such as uniqueness and integration with existing tools and formats. Given the prevalence of public symbols in libraries and frameworks, and debugging symbols in applications, the symbol names themselves can make up a significant portion of binary size. Reducing this impact is a major focus of stabilizing the mangling. Post-ABI-stability, any new manglings or techniques must be additive and must support the existing manglings.
@@ -294,19 +294,19 @@ There are many ways to improve the existing mangling without major impact on exi
### Compact Manglings
-Minor tweaks to shorten the mangling can have a beneficial impact on all Swift program binary sizes. These tweaks should compact existing manglings while preserving a simple unique mapping. One example is not distinguishing between struct/enum in mangling structures, which would also provide more library evolution freedom [[SR-3930](https://bugs.swift.org/browse/SR-3930)]. We are considering dropping some internal witness table symbols when they don't provide any meaningful information conducive to debugging [[SR-3931](https://bugs.swift.org/browse/SR-3931)]. We recently overhauled word substitutions in mangling, with the goal of reducing as much redundancy in names as possible [[SR-4344](https://bugs.swift.org/browse/SR-4344)].
+Minor tweaks to shorten the mangling can have a beneficial impact on all Swift program binary sizes. These tweaks should compact existing manglings while preserving a simple unique mapping. One example is not distinguishing between struct/enum in mangling structures, which would also provide more library evolution freedom [[#46515](https://github.com/apple/swift/issues/46515)]. We are considering dropping some internal witness table symbols when they don't provide any meaningful information conducive to debugging [[#46516](https://github.com/apple/swift/issues/46516)]. We recently overhauled word substitutions in mangling, with the goal of reducing as much redundancy in names as possible [[#46923](https://github.com/apple/swift/issues/46923)].
-There are other aggressive directions to investigate as well, such as mangling based on a known overload set for non-resilient functions. This does have the downside of making manglings unstable when new overloads are added, so its benefits would have to be carefully weighed [[SR-3933](https://bugs.swift.org/browse/SR-3933)].
+There are other aggressive directions to investigate as well, such as mangling based on a known overload set for non-resilient functions. This does have the downside of making manglings unstable when new overloads are added, so its benefits would have to be carefully weighed [[#46518](https://github.com/apple/swift/issues/46518)].
Any more ambitious reimagining of how to store symbols such as aggressive whole-library symbol name compression would have to be done in tight coupling with existing low level tools. Unfortunately, this might make some of the more ambitious options infeasible in time for ABI stability. They could be rolled out as ABI-additive using deployment target checking in the future.
### Suffix Differentiation
-There are many existing low level tools and formats that store and consume the symbol information, and some of them use efficient storage techniques such as tries. Suffix differentiation is about adjusting the mangling in ways that take advantage of them: by distinguishing manglings through suffixes, i.e. having common shared prefixes. This is currently underway and is resulting in binary size reductions for platforms that use these techniques [[SR-3932](https://bugs.swift.org/browse/SR-3932)].
+There are many existing low level tools and formats that store and consume the symbol information, and some of them use efficient storage techniques such as tries. Suffix differentiation is about adjusting the mangling in ways that take advantage of them: by distinguishing manglings through suffixes, i.e. having common shared prefixes. This is currently underway and is resulting in binary size reductions for platforms that use these techniques [[#46517](https://github.com/apple/swift/issues/46517)].
## Calling Convention
-For the purposes of this document, "standard calling convention" refers to the C calling convention for a given platform (see [appendix](#platform-abis)), and "Swift calling convention" refers to the calling convention used by Swift code when calling other Swift code. One of the first steps toward ABI stability is for Swift to adopt the Swift calling convention [[SR-4346](https://bugs.swift.org/browse/SR-4346)]. The Swift runtime uses the standard calling convention, though it may make alterations (see section [Runtime calling convention](#runtime-calling-convention)).
+For the purposes of this document, "standard calling convention" refers to the C calling convention for a given platform (see [appendix](#platform-abis)), and "Swift calling convention" refers to the calling convention used by Swift code when calling other Swift code. One of the first steps toward ABI stability is for Swift to adopt the Swift calling convention [[#46925](https://github.com/apple/swift/issues/46925)]. The Swift runtime uses the standard calling convention, though it may make alterations (see section [Runtime calling convention](#runtime-calling-convention)).
Calling convention stability pertains to public interfaces. The Swift compiler is free to choose any convention for internal (intra-module) functions and calls.
@@ -343,15 +343,15 @@ The specific registers used in these roles are documented in [the calling conven
Function signature lowering is the mapping of a function's source-language type, which includes formal parameters and results, all the way down to a physical convention, which dictates what values are stored in what registers and what values to pass on the stack.
-ABI stability requires nailing down and fully specifying this algorithm so that future Swift versions can lower Swift types to the same physical call signature as prior Swift versions [[SR-4349](https://bugs.swift.org/browse/SR-4349)]. More in-depth descriptions and rationale of function signature lowering can be found in the [function signature lowering docs](https://github.com/apple/swift/blob/main/docs/CallingConvention.rst#function-signature-lowering).
+ABI stability requires nailing down and fully specifying this algorithm so that future Swift versions can lower Swift types to the same physical call signature as prior Swift versions [[#46928](https://github.com/apple/swift/issues/46928)]. More in-depth descriptions and rationale of function signature lowering can be found in the [function signature lowering docs](https://github.com/apple/swift/blob/main/docs/CallingConvention.rst#function-signature-lowering).
-Lowering the result value is usually done first, with a certain number of registers designated to hold the result value if it fits, otherwise the result value is passed on the stack. A good heuristic is needed for the limit and is architecture specific (e.g. 4 registers on modern 64-bit architectures) [[SR-3946](https://bugs.swift.org/browse/SR-3946)].
+Lowering the result value is usually done first, with a certain number of registers designated to hold the result value if it fits, otherwise the result value is passed on the stack. A good heuristic is needed for the limit and is architecture specific (e.g. 4 registers on modern 64-bit architectures) [[#46531](https://github.com/apple/swift/issues/46531)].
Next comes lowering parameters, which proceeds greedily by trying to fit values into registers from left-to-right, though some parameters may be re-ordered. For example, closures are best placed at the end to take advantage of ABI compatibility between thick closures and thin ones without a context.
Some values must be passed and returned indirectly as they are *address only*. Address only values include [non-bitwise-copyable](#type-properties) values, values with [opaque layout](#opaque-layout), and non-class-constrained [existential values](#existential-containers). Even if the runtime type would normally be passed in a register, or even if the type is statically known at the call-site, if the callee receives or returns values with opaque layout, they must be passed or returned indirectly.
-We should investigate whether it makes sense to split values with partially opaque layout by passing the non-opaque parts in registers [[SR-3947](https://bugs.swift.org/browse/SR-3947)].
+We should investigate whether it makes sense to split values with partially opaque layout by passing the non-opaque parts in registers [[#46532](https://github.com/apple/swift/issues/46532)].
Parameter ownership is not reflected in the physical calling convention, though it will be noted in the mangling of the function name. Default argument expressions will not be ABI, as they will be emitted into the caller. This means that a library can add, modify, or remove default argument expressions without breaking binary compatibility (though modifying/removing may break source compatibility).
@@ -383,12 +383,12 @@ Such changes to runtime functions can be rolled out incrementally in the future,
Swift exposes a runtime that provides APIs for compiled code. Calls into the Swift runtime are produced by the compiler for concerns such as memory management and run-time type information. Additionally, the runtime exposes low-level reflection APIs that are useful to the standard library and some users.
-Every existing runtime function will need to be audited for its desirability and behavior [[SR-3735](https://bugs.swift.org/browse/SR-3735)]. For every function, we need to evaluate whether we want the API as is:
+Every existing runtime function will need to be audited for its desirability and behavior [[#46320](https://github.com/apple/swift/issues/46320)]. For every function, we need to evaluate whether we want the API as is:
* If yes, then we need to precisely specify the semantics and guarantees of the API.
* If not, we need to either change, remove, or replace the API, and precisely specify the new semantics.
-The runtime is also responsible for lazily creating new type metadata entries at run time, either for generic type instantiations or for resilient constructs. Library evolution in general introduces a whole new category of needs from the runtime by making data and metadata more opaque, requiring interaction to be done through runtime APIs. Additionally, ownership semantics may require new runtime APIs or modifications to existing APIs. These new runtime needs are still under investigation [[SR-4352](https://bugs.swift.org/browse/SR-4352)].
+The runtime is also responsible for lazily creating new type metadata entries at run time, either for generic type instantiations or for resilient constructs. Library evolution in general introduces a whole new category of needs from the runtime by making data and metadata more opaque, requiring interaction to be done through runtime APIs. Additionally, ownership semantics may require new runtime APIs or modifications to existing APIs. These new runtime needs are still under investigation [[#46931](https://github.com/apple/swift/issues/46931)].
There are many potential future directions to open up the ABI and operate on less-opaque data directly, as well as techniques such as call-site caching. These are ABI-additive, and will be interesting to explore in the future.
@@ -414,9 +414,9 @@ This tradeoff between performance and flexibility also affects the ability to de
While the standard library is already ensuring source stability, it will be changing many of its fundamental underlying representations this year. When ABI stability lands, the standard library will be severely limited in the kinds of changes it can make to existing APIs and non-resilient types. Getting the standard library in the right place is of critical importance.
-The programming model for String is still being redesigned [[SR-4354](https://bugs.swift.org/browse/SR-4354)], and many types such as Int are undergoing implementation changes [[SR-3196](https://bugs.swift.org/browse/SR-3196)]. At the same time, the standard library is simultaneously switching to new compiler features such as conditional conformances to clean up and deliver the best APIs [[SR-3458](https://bugs.swift.org/browse/SR-3458)].
+The programming model for String is still being redesigned [[#46933](https://github.com/apple/swift/issues/46933)], and many types such as Int are undergoing implementation changes [[#45784](https://github.com/apple/swift/issues/45784)]. At the same time, the standard library is simultaneously switching to new compiler features such as conditional conformances to clean up and deliver the best APIs [[#46046](https://github.com/apple/swift/issues/46046)].
-Another goal of Swift is to improve the applicability of Swift to systems programming. Ownership semantics may make a large impact, including things such as improved `inout` semantics that allow for efficient and safe array slicing. Providing the right abstractions for efficient use of contiguous memory is still under investigation [[SR-4355](https://bugs.swift.org/browse/SR-4355)].
+Another goal of Swift is to improve the applicability of Swift to systems programming. Ownership semantics may make a large impact, including things such as improved `inout` semantics that allow for efficient and safe array slicing. Providing the right abstractions for efficient use of contiguous memory is still under investigation [[#46934](https://github.com/apple/swift/issues/46934)].
## Next Steps
diff --git a/docs/Android.md b/docs/Android.md
index c88d551a1f41f..32337b90bc170 100644
--- a/docs/Android.md
+++ b/docs/Android.md
@@ -7,8 +7,9 @@ device running Android or an emulator. This guide explains:
1. How to run a simple "Hello, world" program on your Android device.
2. How to run the Swift test suite on an Android device.
-If you encounter any problems following the instructions below, please file a
-bug using https://bugs.swift.org/.
+If you encounter any problems following the instructions below, please
+[file an issue](https://github.com/apple/swift/issues) and apply the "Android"
+label.
## FAQ
diff --git a/docs/CppInteroperability/CppInteroperabilityStatus.md b/docs/CppInteroperability/CppInteroperabilityStatus.md
index 2febac28adb14..e263d49c46ae9 100644
--- a/docs/CppInteroperability/CppInteroperabilityStatus.md
+++ b/docs/CppInteroperability/CppInteroperabilityStatus.md
@@ -76,7 +76,7 @@ This status table describes which of the following C++ language features can be
| Typedefs / Type aliases | Yes |
| Global Variables | Yes |
| Namespaces | Yes |
-| Inline Namespaces | Yes, with some known issues (https://bugs.swift.org/browse/SR-15956) |
+| Inline Namespaces | Yes, with some known issues ([#58217](https://github.com/apple/swift/issues/58217)) |
| Exceptions | No |
| Fields | Yes |
| Member functions | Yes. Some value category overloads aren't imported |
@@ -120,7 +120,7 @@ This status table describes which of the following C++ standard library features
## Known Issues
### Inline Namespaces
-- https://bugs.swift.org/browse/SR-15956: Swift's typechecker currently doesn't allow calling a function from an inline namespace when it's referenced through the parent namespace. Example of a test that fails: https://github.com/apple/swift/blob/main/test/Interop/Cxx/namespace/inline-namespace-function-call-broken.swift
+- [#58217](https://github.com/apple/swift/issues/58217): Swift's typechecker currently doesn't allow calling a function from an inline namespace when it's referenced through the parent namespace. Example of a test that fails: https://github.com/apple/swift/blob/main/test/Interop/Cxx/namespace/inline-namespace-function-call-broken.swift
## Swift to C++ Interoperability Status
diff --git a/docs/Driver.md b/docs/Driver.md
index 58054d01d5518..f9921f7e37a55 100644
--- a/docs/Driver.md
+++ b/docs/Driver.md
@@ -167,10 +167,8 @@ The output file map accepts other entries, but they should not be considered
stable. Please stick to what's shown here.
(Note: In the example output file map above, all of the per-file outputs are
-being emitted to the same directory. [SR-327][] covers adding a flag that would
-infer this behavior given a directory path.)
-
- [SR-327]: https://bugs.swift.org/browse/SR-327
+being emitted to the same directory. [#42949](https://github.com/apple/swift/issues/42949)
+covers adding a flag that would infer this behavior given a directory path.)
## Whole-Module Optimization ##
@@ -286,9 +284,10 @@ past that, so:
import later.
If you want debugging that's more than `-gline-tables-only`, this is the
- only supported way to do it today. ([SR-2637][] and [SR-2660][] are aimed
- at improving on this.) On the plus side, this mode doesn't strictly need
- an output file map if you give up incremental builds.
+ only supported way to do it today [apple/llvm-project#4588](https://github.com/apple/llvm-project/issues/4588)
+ and [#45265](https://github.com/apple/swift/issues/45265) are aimed at
+ improving on this). On the plus side, this mode doesn't strictly need an
+ output file map if you give up incremental builds.
- Invoke `swiftc -c`, then pass the resulting object files to your linker.
All the same options from above apply, but you'll have to manually deal
@@ -302,10 +301,8 @@ past that, so:
_Can I link all the object files together in the same binary, even if they came
from multiple modules?_
-This is not currently supported, and debugging probably won't work. (See
-[SR-2637][] and [SR-2660][] for more details.) However, if you are using
-`-gnone` or `-gline-tables-only`, the worst you will suffer is more symbols
-being visible than are strictly necessary.
-
- [SR-2637]: https://bugs.swift.org/browse/SR-2637
- [SR-2660]: https://bugs.swift.org/browse/SR-2660
+This is not currently supported, and debugging probably won't work (see
+[apple/llvm-project#4588](https://github.com/apple/llvm-project/issues/4588) and
+[#45265](https://github.com/apple/swift/issues/45265) for more details).
+However, if you are using `-gnone` or `-gline-tables-only`, the worst you will
+suffer is more symbols being visible than are strictly necessary.
diff --git a/docs/DynamicCasting.md b/docs/DynamicCasting.md
index 73b9ffb4802be..880f8d0786448 100644
--- a/docs/DynamicCasting.md
+++ b/docs/DynamicCasting.md
@@ -36,7 +36,7 @@ Where possible, each section includes machine-verifiable _invariants_ that can b
Casting an instance of a type to its own type will always succeed and return the original value unchanged.
-```
+```swift
let a: Int = 7
a is Int // true
a as? Int // Succeeds
@@ -109,13 +109,13 @@ Note: The associated `_ObjectiveCType` is constrained to be a subtype of `AnyObj
In particular, this mechanism is equally available to the Swift implementation of Foundation on non-Apple platforms and the Objective-C Foundation on Apple platforms.
Example #1: Foundation extends the `Array` type in the standard library with an `_ObjectiveCBridgeable` conformance to `NSArray`. This allows Swift arrays to be cast to and from Foundation `NSArray` instances.
-```
+```swift
let a = [1, 2, 3] // Array
let b = a as? AnyObject // casts to NSArray
```
Example #2: Foundation also extends each Swift numeric type with an `_ObjectiveCBridgeable` conformance to `NSNumber`.
-```
+```swift
let a = 1 // Int
// After the next line, b is an Optional
// holding a reference to an NSNumber
@@ -151,7 +151,7 @@ Casting to and from optional types will transparently unwrap optionals as much a
Note: For "Optional Injection" above, the requirement that `t` is a non-nil instance of `T` implies that either `T` is not an `Optional` or that `T` is `Optional` and `t` has the form `.some(u)`
Examples
-```
+```swift
// T and U are any two distinct types (possibly optional)
// NO is any non-optional type
let t: T
@@ -187,7 +187,7 @@ Note that "optional depth" here refers to the number of optional wrappers needed
2. Otherwise, the value should inject with the greatest optional depth possible.
Examples
-```
+```swift
// Depth preservation
// The `.none` here has type `T?` with optional depth 1
let t1: T???? = .some(.some(.some(.none)))
@@ -220,14 +220,14 @@ The result will be a new array where each `Int` in the original array has been i
However, if any component item cannot be cast, then the outer cast will also fail.
For example, consider the following:
-```
+```swift
let a: Array = [Int(7), "string"]
a as? Array // Fails because "string" cannot be cast to `Int`
```
Specifically, the casting operator acts for `Array` as if it were implemented as follows.
In particular, note that an empty array can be successfully cast to any destination array type.
-```
+```swift
func arrayCast(source: Array) -> Optional> {
var result = Array()
for t in source {
@@ -249,7 +249,7 @@ Similar logic applies to `Set` and `Dictionary` casts.
Note that the resulting `Set` or `Dictionary` may have fewer items than the original if the component casting operation converts non-equal items in the source into equal items in the destination.
Specifically, the casting operator acts on `Set` and `Dictionary` as if by the following code:
-```
+```swift
func setCast(source: Set) -> Optional> {
var result = Set()
for t in source {
@@ -382,7 +382,7 @@ For example, its metatype is named `AnyHashable.Type` and it does not have an ex
Any protocol definition (except those that include an `associatedtype` property or which makes use of the `Self` typealias) has an associated existential type named after the protocol.
Specifically, assume you have a protocol definition
-```
+```swift
protocol P {}
```
@@ -427,7 +427,7 @@ We call this type the "metatype of `T`".
Technically, static variables or methods of a type belong to the `T.self` instance and are defined by the metatype of `T`:
Example:
-```
+```swift
struct S {
let ivar = 2
static let svar = 1
@@ -447,7 +447,7 @@ However, in the following cases the metatype has a different name:
* As explained above, although `AnyHashable` behaves like an existential type in some respects, its metatype is called `AnyHashable.Type`.
Example:
-```
+```swift
// Metatype of a struct type
struct S: P {}
S.self is S.Type // always true
@@ -501,7 +501,7 @@ As with other existentials, casting _from_ an existential metatype is equivalent
Casting _to_ an existential metatype succeeds whenever the source is a conforming metatype instance (or can be unwrapped to yield such a metatype instance).
Example
-```
+```swift
protocol P {
var ivar: Int { get }
static svar: Int { get }
@@ -532,7 +532,7 @@ This is equivalent to saying that `P.self` is an instance of `P.Type`.
(Remember that `P.self` is always an instance of `P.Protocol`.)
This is a concern for Swift because of the following construct, which attempts to invoke a generic `f` in a situation where the concrete instance clearly conforms to `P` but is represented as a `P` existential:
-```
+```swift
func f(t: T) { .. use t .. }
let a : P = something
f(a)
@@ -540,7 +540,7 @@ f(a)
This construct is valid only if `T` conforms to `P` when `T = P`; that is, if `P` self-conforms.
A similar situation arises with generic types:
-```
+```swift
struct MyGenericType {
init(_ value: T) { ... }
}
@@ -591,7 +591,7 @@ These are some of the ways in which Swift 5.3 differs from the behavior describe
* Casts for which the target type is "more Optional" than the static source type previously produced errors. This disallowed all of the following: injecting an `Int` into an `Int?`, extracting an `Int?` from an opaque `Any` container, and casting an `Array` to an `Array`. This document allows all of these.
-```
+```swift
let a = 7
// Swift 5.3: error: cannot downcast to a more optional type
// Specification: returns true
@@ -609,7 +609,7 @@ c is Int?
* An instance of a CoreFoundation type could sometimes be cast to a protocol defined on the companion Obj-C type and sometimes not. To make the behavior consistent, we had to choose one; having such casts always succeed seems more consistent with the general dual nature of Obj-C/CF types.
-```
+```swift
import Foundation
protocol P {}
extension NSString: P {}
@@ -625,7 +625,7 @@ print(b is P)
* The Swift 5.3 compiler asserts attempting to cast a struct to AnyObject
-```
+```swift
struct S {}
let s = S()
// Swift 5.3: Compiler crash (in asserts build)
@@ -635,7 +635,7 @@ s as? AnyObject
* `NSNumber()` does not cast to itself via `as?` in unoptimized builds
-```
+```swift
import Foundation
let a = NSNumber()
// true in 5.3 for optimized builds; false for unoptimized builds
@@ -644,7 +644,7 @@ print((a as? NSNumber) != nil)
* `Optional` does not project
-```
+```swift
import Foundation
let a: Optional = NSNumber()
// Swift 5.3: false
@@ -657,7 +657,7 @@ print(a as? NSNumber)
* Casting `NSNumber()` to `Any` crashes at runtime
-```
+```swift
import Foundation
let a = NSNumber()
// Swift 5.3: Runtime crash (both optimized and unoptimized builds)
@@ -665,9 +665,9 @@ let a = NSNumber()
print(a is Any)
```
-* SR-2289: CF types cannot be cast to protocol existentials
+* [#44896](https://github.com/apple/swift/issues/44896): CF types cannot be cast to protocol existentials
-```
+```swift
import Foundation
protocol P {}
extension CFBitVector : P {
@@ -680,9 +680,9 @@ extension CFBitVector : P {
print(CFBitVector.makeImmutable(from: [10,20]) is P)
```
-* SR-4552: Cannot cast `Optional as Any` to protocol type. Note that this is a particular problem for reflection with weak fields, since `Mirror` reflects those as `Any` containing an `Optional` value.
+* [#47129](https://github.com/apple/swift/issues/47129): Cannot cast `Optional as Any` to protocol type. Note that this is a particular problem for reflection with weak fields, since `Mirror` reflects those as `Any` containing an `Optional` value.
-```
+```swift
protocol P {}
class C: P {}
let c: C? = C()
@@ -692,9 +692,9 @@ let a = c as? Any
print(a is P)
```
-* SR-8964: `Any` containing `Optional` cannot cast to `Error`
+* [#51469](https://github.com/apple/swift/issues/51469): `Any` containing `Optional` cannot cast to `Error`
-```
+```swift
struct MyError: Error { }
let a: Any? = MyError()
let b: Any = a
@@ -703,10 +703,10 @@ let b: Any = a
print(b is Error)
```
-* SR-6126: Inconsistent results for nested optionals
+* [#48681](https://github.com/apple/swift/issues/48681): Inconsistent results for nested optionals
-```
-// Note: SR-6126 includes many cases similar to the following
+```swift
+// Note: This issue includes many cases similar to the following
let x: Int? = nil
print(x as Int??) // ==> "Optional(nil)"
// Swift 5.3: prints "nil"
@@ -716,7 +716,7 @@ print((x as? Int??)!)
* `Error.self` does not fully self-conform
-```
+```swift
// Swift 5.3: Prints "false"
// Specification: prints "true"
print(Error.self is Error.Type)
@@ -724,15 +724,15 @@ print(Error.self is Error.Type)
* Objective-C protocol metatypes do not fully self-conform
-```
+```swift
import Foundation
let a = NSObjectProtocol.self
print(a is NSObjectProtocol.Type)
```
-* SR-1999: Cannot cast `Any` contents to a protocol type
+* [#44608](https://github.com/apple/swift/issues/44608): Cannot cast `Any` contents to a protocol type
-```
+```swift
protocol P {}
class Foo: P {}
let optionalFoo: Foo? = Foo()
diff --git a/docs/GenericsManifesto.md b/docs/GenericsManifesto.md
index 9b8931d398310..dc98931e27a2b 100644
--- a/docs/GenericsManifesto.md
+++ b/docs/GenericsManifesto.md
@@ -27,7 +27,7 @@ There are a number of restrictions to the use of generics that fall out of the i
### Recursive protocol constraints (*)
-*This feature has been accepted in [SE-0157](https://github.com/apple/swift-evolution/blob/main/proposals/0157-recursive-protocol-constraints.md) and is tracked by [SR-1445](https://bugs.swift.org/browse/SR-1445).*
+*This feature has been accepted in [SE-0157](https://github.com/apple/swift-evolution/blob/main/proposals/0157-recursive-protocol-constraints.md) and is tracked by [#44054](https://github.com/apple/swift/issues/44054).*
Currently, an associated type cannot be required to conform to its enclosing protocol (or any protocol that inherits that protocol). For example, in the standard library `SubSequence` type of a `Sequence` should itself be a `Sequence`:
@@ -43,7 +43,7 @@ The compiler currently rejects this protocol, which is unfortunate: it effective
### Nested generics
-*This feature was tracked by [SR-1446](https://bugs.swift.org/browse/SR-1446) and was released with Swift 3.1.*
+*This feature was tracked by [#44055](https://github.com/apple/swift/issues/44055) and was released with Swift 3.1.*
Currently, a generic type cannot be nested within another generic type, e.g.
@@ -57,7 +57,7 @@ There isn't much to say about this: the compiler simply needs to be improved to
### Concrete same-type requirements
-*This feature was tracked by [SR-1009](https://bugs.swift.org/browse/SR-1009) and was released with Swift 3.1.*
+*This feature was tracked by [#43621](https://github.com/apple/swift/issues/43621) and was released with Swift 3.1.*
Currently, a constrained extension cannot use a same-type constraint to make a type parameter equivalent to a concrete type. For example:
@@ -114,7 +114,7 @@ Note: generic associatedtypes address many use cases also addressed by higher-ki
### Generic subscripts
-*This feature has been accepted in [SE-0148](https://github.com/apple/swift-evolution/blob/main/proposals/0148-generic-subscripts.md), was tracked by [SR-115](https://bugs.swift.org/browse/SR-115) and was released with Swift 4.*
+*This feature has been accepted in [SE-0148](https://github.com/apple/swift-evolution/blob/main/proposals/0148-generic-subscripts.md), was tracked by [#42737](https://github.com/apple/swift/issues/42737) and was released with Swift 4.*
Subscripts could be allowed to have generic parameters. For example, we could introduce a generic subscript on a `Collection` that allows us to pull out the values at an arbitrary set of indices:
diff --git a/docs/HowToGuides/GettingStarted.md b/docs/HowToGuides/GettingStarted.md
index 807b992c7d24e..36eeb48dee43a 100644
--- a/docs/HowToGuides/GettingStarted.md
+++ b/docs/HowToGuides/GettingStarted.md
@@ -85,7 +85,7 @@ toolchain as a one-off, there are a couple of differences:
**Note:** If you've already forked the project on GitHub at this stage,
**do not clone your fork** to start off. We describe
[how to setup your fork](#setting-up-your-fork) in a subsection below.
-
+
3. Double-check that `swift`'s sibling directories are present.
```sh
ls ..
diff --git a/docs/Lexicon.md b/docs/Lexicon.md
index 2b4d70cf01c63..51264ef16a25a 100644
--- a/docs/Lexicon.md
+++ b/docs/Lexicon.md
@@ -574,11 +574,11 @@ for flow-sensitive diagnostics, optimization, and LLVM IR generation.
## SR
-An issue reported on [bugs.swift.org](https://bugs.swift.org). A
-backronym for "Swift Report"; really the name is derived from LLVM's
-idiomatic use of "PR" ("Problem Report") for its bugs. We didn't go with
-"PR" for Swift because we wanted to be able to unambiguously reference
-LLVM bugs.
+An issue that was originally reported on the now-retired Jira instance that used
+to be located at [bugs.swift.org](https://bugs.swift.org). A backronym for
+"Swift Report"; really the name is derived from LLVM's idiomatic use of "PR"
+("Problem Report") for its bugs. We didn't go with "PR" for Swift because we
+wanted to be able to unambiguously reference LLVM bugs.
## stdlib
diff --git a/docs/StringManifesto.md b/docs/StringManifesto.md
index 7a1b488f2a36b..61e043b6eb48e 100644
--- a/docs/StringManifesto.md
+++ b/docs/StringManifesto.md
@@ -1022,10 +1022,11 @@ domain-specific language (just write ordinary swift code!) and its type safety
problems (put the data right where it belongs!) but the following issues prevent
it from being useful for localized formatting (among other jobs):
- * [SR-2303](https://bugs.swift.org/browse/SR-2303) We are unable to restrict
- types used in string interpolation.
- * [SR-1260](https://bugs.swift.org/browse/SR-1260) String interpolation can't
- distinguish (fragments of) the base string from the string substitutions.
+ * [#44910](https://github.com/apple/swift/issues/44910): We are unable to
+ restrict types used in string interpolation.
+ * [#43868](https://github.com/apple/swift/issues/43868): String interpolation
+ can't distinguish (fragments of) the base string
+ from the string substitutions.
In the long run, we should improve Swift string interpolation to the point where
it can participate in most any formatting job. Mostly this centers around
diff --git a/docs/refactoring/SwiftLocalRefactoring.md b/docs/refactoring/SwiftLocalRefactoring.md
index 90fa2171aced8..738024549bedf 100644
--- a/docs/refactoring/SwiftLocalRefactoring.md
+++ b/docs/refactoring/SwiftLocalRefactoring.md
@@ -334,7 +334,7 @@ following figure illustrates.
## Potential Local Refactoring Ideas
This post just touches on some of the things that are now possible to implement in the new refactoring engine.
If you are excited about extending the refactoring engine to implement additional transformations,
-Swift's [issue database](https://bugs.swift.org) contains [several ideas of refactoring transformations](https://bugs.swift.org/issues/?jql=labels%3DStarterProposal%20AND%20labels%3DRefactoring%20AND%20resolution%3DUnresolved) awaiting implementations.
+Swift's issue database contains [several ideas of refactoring transformations](https://github.com/apple/swift/issues?q=is%3Aissue+is%3Aopen+label%3ARefactoring) awaiting implementations.
For further help with implementing refactoring transformations, please feel free to ask questions on the [Swift forums](https://forums.swift.org/c/development/compiler/9).
diff --git a/docs/tools/swift.pod b/docs/tools/swift.pod
index b1077e3d86a64..48df03bdadffe 100644
--- a/docs/tools/swift.pod
+++ b/docs/tools/swift.pod
@@ -81,8 +81,9 @@ works, continually evolving to make Swift even better.
=head1 BUGS
-Reporting bugs is a great way for anyone to help improve Swift. The bug tracker
-for Swift, an open-source project, is located at L.
+Reporting bugs is a great way for anyone to help improve Swift. The issue
+tracker for Swift, an open-source project, is located at
+L.
If a bug can be reproduced only within an Xcode project or a playground, or if
the bug is associated with an Apple NDA, please file a report to Apple's