Disfavor shared optional dynamic member lookup

Sources/ComposableArchitecture/Documentation.docc/Articles/MigrationGuides/MigratingTo1.11.md

@@ -98,3 +98,59 @@ references:
   )
 )
 ```
+
+## Migrating to 1.11.1
+
+A few bug fixes landed in 1.11.1 that may be source breaking. They are described below:
+
+### `withLock` is now `@MainActor`
+
+In [version 1.11](<doc:MigratingTo1.11>) of the library we deprecated mutating shared state from
+asynchronous contexts, such as effects, and instead recommended using the new 
+``Shared/withLock(_:)`` method. Doing so made it possible to lock all mutations to the shared state
+and prevent race conditions (see the [migration guide](<doc:MigratingTo1.11>) for more info).
+
+However, this did leave open the possibility for deadlocks if shared state was read from and written
+to on different threads. To fix this we have now restricted ``Shared/withLock(_:)`` to the
+`@MainActor`, and so you will now need to `await` its usage:
+
+```diff
+-sharedCount.withLock { $0 += 1 }
++await sharedCount.withLock { $0 += 1 }
+```
+
+The compiler should suggest this fix-it for you.
+
+### Optional dynamic member lookup on `Shared` is deprecated/disfavored
+
+When the ``Shared`` property wrapper was first introduced, its dynamic member lookup was overloaded
+to automatically unwrap optionals for ergonomic purposes:
+
+```swift
+if let sharedUnwrappedProperty = $shared.optionalProperty {
+  // ...
+}
+```
+
+This unfortunately made dynamic member lookup a little more difficult to understand:
+
+```swift
+$shared.optionalProperty  // Shared<Value>?, *not* Shared<Value?>
+```
+
+…and required casting and other tricks to transform shared values into what one might expect.
+
+And so this dynamic member lookup is deprecated and has been disfavored, and will eventually be
+removed entirely. Instead, you can use ``Shared/init(_:)`` to explicitly unwrap a shared optional
+value.
+
+Disfavoring it does have the consequence of being source breaking in the case of `if let` and
+`guard let` expressions, where Swift does not select the optional overload automatically. To
+migrate, use ``Shared/init(_:)``:
+
+```diff
+-if let sharedUnwrappedProperty = $shared.optionalProperty {
++if let sharedUnwrappedProperty = Shared($shared.optionalProperty) {
+   // ...
+ }
+```

Sources/ComposableArchitecture/SharedState/Shared.swift

@@ -173,6 +173,7 @@ public struct Shared<Value> {
     Shared<Member>(reference: self.reference, keyPath: self.keyPath.appending(path: keyPath)!)
   }
 
+  @_disfavoredOverload
   @available(
     *, deprecated, message: "Use 'Shared($value.optional)' to unwrap optional shared values"
   )
@@ -434,6 +435,7 @@ extension Shared {
     SharedReader(reference: self.reference, keyPath: self.keyPath)
   }
 
+  @_disfavoredOverload
   @available(
     *, deprecated, message: "Use 'SharedReader($value.optional)' to unwrap optional shared values"
   )

Sources/ComposableArchitecture/SharedState/SharedReader.swift

@@ -122,6 +122,7 @@ public struct SharedReader<Value> {
     SharedReader<Member>(reference: self.reference, keyPath: self.keyPath.appending(path: keyPath)!)
   }
 
+  @_disfavoredOverload
   @available(
     *, deprecated, message: "Use 'SharedReader($value.optional)' to unwrap optional shared values"
   )