1# Handling Soft-Deprecated APIs
2 
3This file covers *how to behave* when you encounter soft-deprecated SwiftUI APIs. For the actual list of deprecated-to-modern transitions, see `references/latest-apis.md`.
4 
5## What "soft-deprecated" means
6 
7A soft-deprecated API is marked deprecated in the SDK headers but with a placeholder deprecation version (`100000.0`) that suppresses compiler warnings. It still compiles and works correctly — it just signals that the API shouldn't be used in new code. Examples include `NavigationView` (use `NavigationStack` / `NavigationSplitView`), `ActionSheet` / `Alert` (use the `.confirmationDialog` / `.alert` modifiers), `MagnificationGesture` (renamed `MagnifyGesture`), and `PresentationMode` (use `\.dismiss`).
8 
9Because these still work, treat them as **informational**, not urgent.
10 
11## Scoping rule — read this first
12 
13All soft-deprecation guidance is scoped to the code you are **directly modifying**. If a file contains several views and the task touches only one, the other views are out of scope.
14 
15- Only discuss the view(s) you actually edited.
16- Do not mention, flag, or offer to migrate soft-deprecated APIs in code you weren't asked to change — including trailing "while I'm here, want me to migrate `OtherView`?" questions.
17- This takes precedence over any prompt asking for "observations" or "other notes."
18 
19Mentioning soft-deprecated APIs in untouched code creates noise, distracts from the task, and pressures the user into unrelated work.
20 
21## When generating new code
22 
23Never introduce a new usage of a soft-deprecated API. If you're unsure whether an API is soft-deprecated, check `references/latest-apis.md` before recommending it — any API that worked in a prior release could have been soft-deprecated since.
24 
25## When asked to review, refactor, modernize, or clean up
26 
27Point out soft-deprecated APIs in the code under review and suggest the modern replacement. Keep the tone informational — these still compile and run, so frame migration as an improvement, not a bug fix.
28 
29## When asked to add a feature or fix a bug
30 
31If the view you're editing already uses a soft-deprecated API, **keep it as-is** in your change. Don't silently swap `NavigationView` for `NavigationStack` while adding a search bar — that produces unexpected diffs, risks regressions (state resets, navigation behavior changes), and makes the change harder to review. After delivering the requested change, you may add a brief one-line offer to migrate as a separate step.
32 
33If a *different* view in the same file uses a soft-deprecated API, ignore it entirely (see the scoping rule).
34 
35## General guidance
36 
37- Never introduce new usages of soft-deprecated APIs in code written from scratch.
38- Don't proactively scan a codebase for soft-deprecated APIs — only notice them when they appear in code you're directly modifying for the user's request.
39- Migrations are real edits with behavioral risk; they belong in their own focused change, not bundled into unrelated work.
40