40 lines
2.9 KiB
Markdown
40 lines
2.9 KiB
Markdown
# 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.
|