2.9 KiB
Handling Soft-Deprecated APIs
This 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.
What "soft-deprecated" means
A 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).
Because these still work, treat them as informational, not urgent.
Scoping rule — read this first
All 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.
- Only discuss the view(s) you actually edited.
- 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. - This takes precedence over any prompt asking for "observations" or "other notes."
Mentioning soft-deprecated APIs in untouched code creates noise, distracts from the task, and pressures the user into unrelated work.
When generating new code
Never 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.
When asked to review, refactor, modernize, or clean up
Point 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.
When asked to add a feature or fix a bug
If 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.
If a different view in the same file uses a soft-deprecated API, ignore it entirely (see the scoping rule).
General guidance
- Never introduce new usages of soft-deprecated APIs in code written from scratch.
- 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.
- Migrations are real edits with behavioral risk; they belong in their own focused change, not bundled into unrelated work.