Add migration guide for 1.16. (#3491)

* Add migration guide for 1.16.

* Update README.md

---------

Co-authored-by: Stephen Celis <[email protected]>

Author: mbrandonw

README.md

@@ -532,13 +532,14 @@ advanced usages.
 The documentation for releases and `main` are available here:
 
 * [`main`](https://pointfreeco.github.io/swift-composable-architecture/main/documentation/composablearchitecture/)
-* [1.15.0](https://pointfreeco.github.io/swift-composable-architecture/1.15.0/documentation/composablearchitecture/) ([migration guide](https://pointfreeco.github.io/swift-composable-architecture/main/documentation/composablearchitecture/migratingto1.15))
+* [1.16.0](https://pointfreeco.github.io/swift-composable-architecture/1.16.0/documentation/composablearchitecture/) ([migration guide](https://pointfreeco.github.io/swift-composable-architecture/main/documentation/composablearchitecture/migratingto1.16))
 
 <details>
   <summary>
   Other versions
   </summary>
 
+  * [1.15.0](https://pointfreeco.github.io/swift-composable-architecture/1.15.0/documentation/composablearchitecture/) ([migration guide](https://pointfreeco.github.io/swift-composable-architecture/main/documentation/composablearchitecture/migratingto1.15))
   * [1.14.0](https://pointfreeco.github.io/swift-composable-architecture/1.14.0/documentation/composablearchitecture/) ([migration guide](https://pointfreeco.github.io/swift-composable-architecture/main/documentation/composablearchitecture/migratingto1.14))
   * [1.13.0](https://pointfreeco.github.io/swift-composable-architecture/1.13.0/documentation/composablearchitecture/) ([migration guide](https://pointfreeco.github.io/swift-composable-architecture/main/documentation/composablearchitecture/migratingto1.13))
   * [1.12.0](https://pointfreeco.github.io/swift-composable-architecture/1.12.0/documentation/composablearchitecture/) ([migration guide](https://pointfreeco.github.io/swift-composable-architecture/main/documentation/composablearchitecture/migratingto1.12))

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

@@ -14,6 +14,7 @@ APIs, and these guides contain tips to do so.
 
 ## Topics
 
+- <doc:MigratingTo1.16>
 - <doc:MigratingTo1.15>
 - <doc:MigratingTo1.14>
 - <doc:MigratingTo1.13>

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

@@ -0,0 +1,32 @@
+# Migrating to 1.16
+
+The `.appStorage` strategy used with `@Shared` now uses key-value observing instead of 
+`NotificationCenter` when possible. Learn how this may affect your code.
+
+## Overview
+
+There are no steps needed to migrate to 1.16 of the Composable Architecture, but there has been
+a change to the underlying behavior of `.appStorage` that one should be aware of. When using
+`.appStorage` with `@Shared`, if your key does not contain the characters "." or "@", then changes 
+to that key in `UserDefaults` will be observed using key-value observing (KVO). 
+Otherwise, `NotificationCenter` will be used to observe changes.
+
+KVO is a far more efficient way of observing changes to `UserDefaults` and it works cross-process,
+such as from widgets and app extensions. However, KVO does not work when the keys contain "."
+or "@", and so in those cases we must use the cruder tool of `NotificationCenter`. That is not
+as efficient, and it forces us to perform a thread-hop when the notification is posted before
+we can update the `@Shared` value. For this reason it is not possible to animate changes that are
+made directly to `UserDefaults`:
+
+```swift
+withAnimation {
+  // ⚠️ This will not animate any SwiftUI views using '@Shared(.appStorage("co.pointfree.count"))'
+  UserDefaults.standard.set(0, forKey: "co.pointfree.count")
+}
+```
+
+In general, we recommend using other delimeters for your keys, such as "/", ":", "-", etc.:
+
+```swift
+@Shared(.appStorage("co:pointfree:count")) var count = 0
+```

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

@@ -279,7 +279,7 @@ enum Action {
 ```
 
 And in the reducer, instead of invoking 
-``Reducer/forEach(_:action:element:fileID:filePath:line:column:)-3dw7i`` with a case path using the 
+``Reducer/forEach(_:action:element:fileID:filePath:line:column:)-6zye8`` with a case path using the 
 `/` prefix operator:
 
 ```swift

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

@@ -904,7 +904,7 @@ func viewDidLoad() {
 }
 ```
 
-This can now be done more simply using the ``ObjectiveC/NSObject/observe(_:)`` method defined on
+This can now be done more simply using the ``ObjectiveC/NSObject/observe(_:)-94oxy`` method defined on
 all `NSObject`s:
 
 ```swift
@@ -920,7 +920,7 @@ func viewDidLoad() {
 }
 ```
 
-Be sure to read the documentation for ``ObjectiveC/NSObject/observe(_:)`` to learn how to best 
+Be sure to read the documentation for ``ObjectiveC/NSObject/observe(_:)-94oxy`` to learn how to best 
 wield this tool.
 
 ### Replacing Store.ifLet
@@ -940,7 +940,7 @@ store
 ```
 
 This can now be done more simply using the `observe` method and
-``Store/scope(state:action:fileID:filePath:line:column:)-2ck1n``:
+``Store/scope(state:action:fileID:filePath:line:column:)-3yvuf``:
 
 ```swift
 observe {

Sources/ComposableArchitecture/Documentation.docc/Articles/SharingState.md

@@ -318,7 +318,7 @@ should take a plain, non-`Shared` value and you construct the `Shared` value in
 * You are using a persistence strategy with shared state (_e.g._ 
 ``PersistenceReaderKey/appStorage(_:)-4l5b``, ``PersistenceReaderKey/fileStorage(_:decoder:encoder:)``, _etc._),
 then the initializer should take a plain, non-`Shared` value and you construct the `Shared` value in
-the initializer using ``Shared/init(wrappedValue:_:fileID:line:)-512rh`` which takes a
+the initializer using ``Shared/init(wrappedValue:_:fileID:line:)-9kfmy`` which takes a
 ``PersistenceKey`` as the second argument:
 
   ```swift
@@ -338,7 +338,7 @@ the initializer using ``Shared/init(wrappedValue:_:fileID:line:)-512rh`` which t
 
   > Important: The value passed to this initializer is only used if the external storage does not
   > already have a value. If a value exists in the storage then it is not used. In fact, the
-  > `wrappedValue` argument of ``Shared/init(wrappedValue:_:fileID:line:)-512rh`` is an
+  > `wrappedValue` argument of ``Shared/init(wrappedValue:_:fileID:line:)-9kfmy`` is an
   > `@autoclosure` so that it is not even evaluated if not used. For that reason you
   > may prefer to make the argument to the initializer an `@autoclosure` so that it too is evaluated
   > only if actually used:
@@ -436,7 +436,7 @@ responsible for persisting and deriving shared state to pass to the child.
 If your shared state is a collection, and in particular an `IdentifiedArray`, then we have another
 tool for deriving shared state to a particular element of the array. You can subscript into a 
 ``Shared`` collection with the `[id:]` subscript, and that will give a piece of optional shared
-state (thanks to a dynamic member overload ``Shared/subscript(dynamicMember:)-7ibhr``), which you
+state (thanks to a dynamic member overload ``Shared/subscript(dynamicMember:)-9xw64``), which you
 can then unwrap to turn into honest shared state:
 
 ```swift
@@ -1071,7 +1071,7 @@ own implementations of `encode(to:)` and `init(from:)` that do the appropriate t
 For example, if the data type is sharing state with a persistence strategy, you can decode by 
 delegating to the memberwise initializer that implicitly loads the shared value from the property 
 wrapper's persistence strategy, or you can explicitly initialize a shared value via
-``Shared/init(wrappedValue:_:fileID:line:)-512rh``. And for encoding you can often skip encoding 
+``Shared/init(wrappedValue:_:fileID:line:)-9kfmy``. And for encoding you can often skip encoding 
 the shared value:
 
 ```swift

Sources/ComposableArchitecture/Documentation.docc/Extensions/AppStorageKey.md

@@ -4,29 +4,29 @@
 
 ### Storing a value
 
-- ``PersistenceReaderKey/appStorage(_:)-4l5b``
-- ``PersistenceReaderKey/appStorage(_:)-6d47p``
-- ``PersistenceReaderKey/appStorage(_:)-6tsph``
-- ``PersistenceReaderKey/appStorage(_:)-69h4r``
-- ``PersistenceReaderKey/appStorage(_:)-xphy``
-- ``PersistenceReaderKey/appStorage(_:)-617ld``
-- ``PersistenceReaderKey/appStorage(_:)-6lnxu``
-- ``PersistenceReaderKey/appStorage(_:)-ibg0``
+- ``PersistenceReaderKey/appStorage(_:)-4l5b``  <!-- Bool -->
+- ``PersistenceReaderKey/appStorage(_:)-6d47p`` <!-- Data -->
+- ``PersistenceReaderKey/appStorage(_:)-6tsph`` <!-- Double -->
+- ``PersistenceReaderKey/appStorage(_:)-69h4r`` <!-- Integer -->
+- ``PersistenceReaderKey/appStorage(_:)-xphy``  <!-- String -->
+- ``PersistenceReaderKey/appStorage(_:)-617ld`` <!-- URL -->
+- ``PersistenceReaderKey/appStorage(_:)-6k27r`` <!-- RawRepresentable<Int> -->
+- ``PersistenceReaderKey/appStorage(_:)-m54v``  <!-- RawRepresentable<String> -->
 
 ### Storing an optional value
 
-- ``PersistenceReaderKey/appStorage(_:)-4s3s5``
-- ``PersistenceReaderKey/appStorage(_:)-2dfnh``
-- ``PersistenceReaderKey/appStorage(_:)-5wv8g``
-- ``PersistenceReaderKey/appStorage(_:)-40e42``
-- ``PersistenceReaderKey/appStorage(_:)-4veqp``
-- ``PersistenceReaderKey/appStorage(_:)-7rox5``
-- ``PersistenceReaderKey/appStorage(_:)-2keyn``
-- ``PersistenceReaderKey/appStorage(_:)-7u49u``
+- ``PersistenceReaderKey/appStorage(_:)-4s3s5`` <!-- Bool -->
+- ``PersistenceReaderKey/appStorage(_:)-2dfnh`` <!-- Data -->
+- ``PersistenceReaderKey/appStorage(_:)-5wv8g`` <!-- Double -->
+- ``PersistenceReaderKey/appStorage(_:)-40e42`` <!-- Integer -->
+- ``PersistenceReaderKey/appStorage(_:)-4veqp`` <!-- String -->
+- ``PersistenceReaderKey/appStorage(_:)-7rox5`` <!-- URL -->
+- ``PersistenceReaderKey/appStorage(_:)-2cfq9`` <!-- RawRepresentable<Int> -->
+- ``PersistenceReaderKey/appStorage(_:)-9j150`` <!-- RawRepresentable<String> -->
 
 ### Key-path access
 
-- ``PersistenceReaderKey/appStorage(_:)-5jsie``
+- ``PersistenceReaderKey/appStorage(_:)-69h4r``
 - ``AppStorageKeyPathKey``
 
 ### Overriding app storage

Sources/ComposableArchitecture/Documentation.docc/Extensions/Deprecations/ReducerDeprecations.md

@@ -15,7 +15,7 @@ instead.
 - ``Reducer/ifLet(_:action:destination:fileID:filePath:line:column:)-5y8z4``
 - ``Reducer/ifLet(_:action:fileID:filePath:line:column:)-12kry``
 - ``Reducer/ifCaseLet(_:action:then:fileID:filePath:line:column:)-403y9``
-- ``Reducer/forEach(_:action:element:fileID:filePath:line:column:)-1oguc``
+- ``Reducer/forEach(_:action:element:fileID:filePath:line:column:)-o1gn``
 - ``Reducer/forEach(_:action:destination:fileID:filePath:line:column:)-74erx``
 - ``Reducer/onChange(of:removeDuplicates:_:)``
 

Sources/ComposableArchitecture/Documentation.docc/Extensions/Reducer.md

@@ -581,7 +581,7 @@ xcodebuild -skipMacroValidation …
 - ``Scope``
 - ``ifLet(_:action:then:fileID:filePath:line:column:)-2r2pn``
 - ``ifCaseLet(_:action:then:fileID:filePath:line:column:)-7sg8d``
-- ``forEach(_:action:element:fileID:filePath:line:column:)-3dw7i``
+- ``forEach(_:action:element:fileID:filePath:line:column:)-6zye8``
 - <doc:Navigation>
 
 ### Sharing state

Sources/ComposableArchitecture/Documentation.docc/Extensions/ReducerForEach.md

@@ -1,4 +1,4 @@
-# ``ComposableArchitecture/Reducer/forEach(_:action:element:fileID:filePath:line:column:)-3dw7i``
+# ``ComposableArchitecture/Reducer/forEach(_:action:element:fileID:filePath:line:column:)-6zye8``
 
 ## Topics