ios-sdk-upgrade
Skill1 starsChanged 16 days agoMITView on GitHub
Move an iOS app to a new Xcode and iOS SDK (currently Xcode 27 / iOS 27 SDK) — host requirements, build breaks, behaviour changes that apply just by rebuilding, deprecations, and App Store upload deadlines. Use when upgrading Xcode, when a project stops building or launching after an Xcode update, or when Apple announces a new minimum SDK for App Store uploads. Not for adopting new features (see ios-latest-os-adoption) or Swift 6 language mode (see ios-swift6-concurrency-migration).
In this repository37 other files it gives its agents.
- AGENTS.mdAGENTS.md
- ios-accessibility-auditSkill
- ios-api-contract-migrationSkill
- ios-api-endpointSkill
- ios-app-intents-siriSkill
- ios-bug-triageSkill
- ios-build-configurationSkill
- ios-cloudkit-syncSkill
- ios-combine-patternsSkill
- ios-commit-and-prSkill
- ios-commitSkill
- ios-concurrency-auditSkill
- ios-coreml-apple-intelligenceSkill
- ios-deep-linkingSkill
- ios-dependency-assessmentSkill
- ios-design-fixSkill
- ios-feature-moduleSkill
- ios-knowledge-baseSkill
- ios-latest-os-adoptionSkill
- ios-localizationSkill
- ios-offline-writeSkill
- ios-performance-tuningSkill
- ios-port-from-androidSkill
- ios-port-to-androidSkill
- ios-precommitSkill
- ios-privacy-complianceSkill
- ios-push-and-background-tasksSkill
- ios-refactorSkill
- ios-release-prepSkill
- ios-secure-reviewSkill
- ios-storekit-subscriptionsSkill
- ios-swift6-concurrency-migrationSkill
- ios-swiftdataSkill
- ios-swift-testing-migrationSkill
- ios-swiftui-screenSkill
- ios-unit-testsSkill
- ios-widgetkit-live-activitiesSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 68
Check *Upcoming Requirements* for any other dated requirement before each release.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Upgrade to a new Xcode and SDK
Building with a new SDK changes behaviour even with no code change: some APIs switch implementation, some requirements become mandatory, and some deprecated paths stop working. Treat the upgrade as its own change, separate from feature work, so a regression can be traced to it.
0. Read Apple's notes first, not memory
For the target versions, read Apple's Xcode Release Notes and iOS & iPadOS Release Notes (developer.apple.com/documentation), and the Upcoming Requirements page (developer.apple.com/news/upcoming-requirements). The checklist below was checked against the Xcode 27 / iOS 27 notes; re-check it for any later release.
1. Can this machine and CI build at all?
Xcode 27 (checked October 2026):
- Runs only on Apple silicon Macs, and needs macOS Tahoe 26.6 or later. Update CI runners/images first; an Intel build agent can no longer run it.
- Includes Swift 6.4. Language mode doesn't change by itself, but new warnings appear.
- On-device debugging needs iOS 17 or later; older test devices can't be debugged.
2. Build breaks to fix (Xcode 27 / iOS 27 SDK)
| Change | What breaks | Fix |
ld64 removed; -ld_classic no longer supported | Builds passing -ld_classic or -ld64 in OTHER_LDFLAGS | Remove the flag; fix whatever it was working around |
@State is now a macro | @State with an initial value and assigned in init; @State combined with another property wrapper or macro; some generic inference; the synthesized private memberwise init of a struct whose stored members are all private | Give the value in only one place; write types explicitly; write the init yourself |
| SE-0508 known source break | A computed property with an init accessor and an array/dictionary literal initial value, getter written first | Put the init accessor first |
| Unique Clang module names | Duplicate module names in the dependency graph may error | Rename one module |
3. Launch and runtime requirements (iOS 27 SDK)
- Scene-based life cycle is required. Apps built with the latest SDK that don't adopt
it fail to launch. UIKit apps need a scene configuration and a
UISceneDelegate; move app-delegate window and lifecycle code into it. SwiftUIAppapps already comply. - A launch screen is required.
Info.plistmust containUILaunchStoryboardName,UILaunchStoryboards,UILaunchScreenorUILaunchScreens, or App Store uploads are rejected. TabViewselection must be a visible tab — setting it to a hidden or unavailable tab can now crash.- Presented view controllers inherit traits through the view hierarchy, not directly
from the presentation controller. Check custom
UIPresentationControllersubclasses. - Selectable
Textuses the system text-selection UI, with extra gestures. Check screens that put.textSelection(.enabled)inside gesture-heavy containers.
4. Deprecations to plan (warnings only, no deadline yet)
PreviewProviderand its preview modifiers →#Preview.canOpenURL(_:)→ open the URL and handle failure; prefer Universal Links (ios-deep-linking).FileDocument→ReadableDocument/Document.- Original MetricKit (
MXMetricManager,MXMetricPayload…) →MetricManager(ios-performance-tuning). Recompile if you referenceScrollHitchTimeMetric, or it crashes at launch on iOS 27.
Fix deprecations in their own commits, after the app builds and launches cleanly.
5. Deadlines
- From April 2027, App Store uploads for iOS and iPadOS must be built with the iOS 27 SDK or later. Plan the upgrade to land well before that, including a TestFlight cycle.
- Check Upcoming Requirements for any other dated requirement before each release.
6. Order of work
- Upgrade CI and one developer machine; build on a branch.
- Fix build breaks (§2) until it compiles with no new errors.
- Fix launch/runtime requirements (§3); run the app on the newest OS and the oldest supported OS.
- Full test suite; then
ios-accessibility-auditand a visual pass on key screens (system components can look different after a rebuild). - Deprecations (§4), each in its own commit.
- Record the upgrade (Xcode/SDK/Swift versions, date) in the knowledge base.
Verification
- Apple's release notes for the exact Xcode and SDK versions were read; anything here that changed in a later release was updated.
- CI and local machines meet the host requirements; CI builds with the new Xcode.
- No
-ld_classic/-ld64flags remain; the app builds with no new errors. - Scene-based life cycle adopted and a launch-screen key present in
Info.plist. - App launches and the main flows work on the newest OS and the oldest supported OS.
- Test suite green; visual and accessibility pass done on key screens.
- Remaining deprecations listed with owners; upload deadline noted in the release plan.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

