Soft-deprecate Store.ifLet (#3382)

* Soft-deprecate `Store.ifLet`

We can prefer `observe` and `if let store.scope` now.

* wip

* wip

* Update MigratingTo1.7.md

* wip

.github/workflows/ci.yml

@@ -21,19 +21,19 @@ jobs:
  matrix:
  command: [test, '']
  platform: [iOS, macOS, tvOS, watchOS, visionOS, macCatalyst]
- xcode: [15.2, 15.4, 16_beta_6]
- exclude: 
+ xcode: [15.2, 15.4, '16.0']
+ exclude:
  - {xcode: 15.2, command: test}
  - {xcode: 15.4, command: ''}
  - {xcode: 15.2, platform: macCatalyst}
  - {xcode: 15.2, platform: tvOS}
  - {xcode: 15.2, platform: visionOS}
  - {xcode: 15.2, platform: watchOS}
- - {xcode: 16_beta_6, command: ''}
- - {xcode: 16_beta_6, platform: macCatalyst}
- - {xcode: 16_beta_6, platform: tvOS}
- - {xcode: 16_beta_6, platform: visionOS}
- - {xcode: 16_beta_6, platform: watchOS}
+ - {xcode: '16.0', command: ''}
+ - {xcode: '16.0', platform: macCatalyst}
+ - {xcode: '16.0', platform: tvOS}
+ - {xcode: '16.0', platform: visionOS}
+ - {xcode: '16.0', platform: watchOS}
  include:
  - {xcode: 15.2, skip_release: 1}
  steps:
@@ -83,7 +83,7 @@ jobs:
  restore-keys: |
  deriveddata-examples-
  - name: Select Xcode 16
- run: sudo xcode-select -s /Applications/Xcode_16_beta_6.app
+ run: sudo xcode-select -s /Applications/Xcode_16.0.app
  - name: Set IgnoreFileSystemDeviceInodeChanges flag
  run: defaults write com.apple.dt.XCBuild IgnoreFileSystemDeviceInodeChanges -bool YES
  - name: Update mtime for incremental builds

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

@@ -889,6 +889,8 @@ rather than going through ``Store/send(_:)``:
 
 ## Observing for UIKit
 
+### Replacing Store.publisher
+
 Prior to the observation tools one would typically subscribe to changes in the store via a Combine
 publisher in the entry point of a view, such as `viewDidLoad` in a `UIViewController` subclass:
 
@@ -921,6 +923,35 @@ func viewDidLoad() {
 Be sure to read the documentation for ``ObjectiveC/NSObject/observe(_:)`` to learn how to best 
 wield this tool.
 
+### Replacing Store.ifLet
+
+Prior to the observation tools one would typically subscribe to optional child stores via a Combine
+operation provided by the library:
+
+```swift
+store
+ .scope(state: \.child, action: \.child)
+ .ifLet { childStore in
+ // Use child store, _e.g._ create a child view controller
+ } else: {
+ // Perform clean up work, _e.g._ dismiss child view controller
+ }
+ .store(in: &cancellables)
+```
+
+This can now be done more simply using the `observe` method and
+``Store/scope(state:action:fileID:filePath:line:column:)-2ck1n``:
+
+```swift
+observe {
+ if let childStore = store.scope(state: \.child, action: \.child) {
+ // Use child store, _e.g._ create a child view controller
+ } else {
+ // Perform clean up work, _e.g._ dismiss child view controller
+ }
+}
+```
+
 ## Incrementally migrating
 
 You are most likely going to want to incrementally migrate your application to the new observation tools, 

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

@@ -12,3 +12,7 @@ instead.
 ### Scoping stores
 
 - ``Store/scope(state:action:)-9iai9``
+
+### UIKit integration
+
+- ``ifLet(then:else:)``

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

@@ -35,10 +35,6 @@
 
 - ``StorePublisher``
 
-### UIKit integration
-
-- ``ifLet(then:else:)``
-
 ### Deprecated interfaces
 
 - <doc:StoreDeprecations>

Sources/ComposableArchitecture/UIKit/IfLetUIKit.swift

@@ -45,6 +45,10 @@ extension Store {
  /// goes from non-`nil` to `nil`.
  /// - Returns: A cancellable that maintains a subscription to updates whenever the store's state
  /// goes from `nil` to non-`nil` and vice versa, so that the caller can react to these changes.
+ @available(iOS, deprecated: 9999, message: "Use 'observe' and 'if let store.scope', instead.")
+ @available(macOS, deprecated: 9999, message: "Use 'observe' and 'if let store.scope', instead.")
+ @available(tvOS, deprecated: 9999, message: "Use 'observe' and 'if let store.scope', instead.")
+ @available(watchOS, deprecated: 9999, message: "Use 'observe' and 'if let store.scope', instead.")
  public func ifLet<Wrapped>(
  then unwrap: @escaping (_ store: Store<Wrapped, Action>) -> Void,
  else: @escaping () -> Void = {}