Swift 6 Migration

Overview

Swift 6 enforces data race safety at compile time. Migration involves making implicit isolation explicit and ensuring all shared state is thread-safe.

This skill bundles Apple's complete migration guide. You MUST search it for EVERY error before implementing a fix.

Mandatory Workflow

digraph migration_workflow {
    rankdir=TB;
    node [shape=box];

    "Compiler error/warning" [shape=ellipse];
    "Search migration-guide.md" [label="REQUIRED: Search migration-guide.md\nfor error pattern"];
    "Read matched section" [label="Read the matched FILE: section"];
    "Apply documented fix" [label="Apply Apple's documented fix"];
    "Verify fix" [label="Build and verify"];

    "Compiler error/warning" -> "Search migration-guide.md";
    "Search migration-guide.md" -> "Read matched section";
    "Read matched section" -> "Apply documented fix";
    "Apply documented fix" -> "Verify fix";
    "Verify fix" -> "Compiler error/warning" [label="More errors"];
}

For EACH compiler error/warning:

FIRST search migration-guide.md for the error pattern
THEN read the matched FILE: section
THEN apply the documented fix
FINALLY verify the fix

Checklist

Use TodoWrite to track each item:

Enable -strict-concurrency=complete warnings before Swift 6 mode
For EACH error: grep migration-guide.md BEFORE implementing fix
Read the relevant FILE: section from search results
Verify fix matches Apple's documented approach
Test runtime behavior after fixes (execution order may change)

Required Searches by Error Type

You MUST run these searches. Do not skip to Quick Reference.

Error Pattern	Required Search Command
`global variable is not concurrency-safe`	`grep -n -A 30 "Unsafe Global" migration-guide.md`
`does not conform to.*Sendable`	`grep -n -A 30 "Sendable Types" migration-guide.md`
`cannot pass argument of non-sendable type`	`grep -n -A 30 "ConformanceMismatches" migration-guide.md`
`actor-isolated.*cannot be referenced`	`grep -n -A 30 "actor-isolated" migration-guide.md`
`@preconcurrency` needed	`grep -n -A 30 "PreconcurrencyImport" migration-guide.md`
`Task` or async/await migration	`grep -n -A 30 "Boundaries.swift" migration-guide.md`
GCD/DispatchQueue migration	`grep -n -A 30 "DispatchQueue" migration-guide.md`

Quick Reference (Starting Points Only)

These are shortcuts for orientation. You MUST verify against migration-guide.md before applying.

Problem	Likely Direction	Verify With
Mutable global var	`let`, `@MainActor`, or actor	`grep -n "Globals.swift" migration-guide.md`
Non-Sendable class	`Sendable`, `@unchecked Sendable`, or actor	`grep -n "Sendable" migration-guide.md`
Actor isolation error	`await`, `nonisolated`, or `@MainActor`	`grep -n "actor-isolated" migration-guide.md`
Closure capturing	`@Sendable` closure or restructure	`grep -n "closure" migration-guide.md`
Legacy callback API	`withCheckedContinuation`	`grep -n "continuation" migration-guide.md`

Commands

# Build with complete concurrency checking (warnings)
swift build -Xswiftc -strict-concurrency=complete

# Build in Swift 6 mode (errors)
swift build -Xswiftc -swift-version -Xswiftc 6

Package.swift settings:

// Enable strict concurrency per target
.target(
    name: "MyTarget",
    swiftSettings: [.enableExperimentalFeature("StrictConcurrency")]
)

// Or enable Swift 6 mode
swiftLanguageVersions: [.v6]

Common Mistakes

Mistake	Why It's Wrong	Better Approach
Adding `@unchecked Sendable` everywhere	Hides real data races	Search guide first: `grep -n "unchecked" migration-guide.md`
Using `nonisolated(unsafe)`	Compiler trusts you but runtime doesn't	Search: `grep -n "nonisolated" migration-guide.md`
Skipping the migration guide	Miss Apple's recommended patterns	ALWAYS search before fixing

Red Flags - STOP and Search First

These thoughts mean you're about to skip required verification:

"I know how to fix this"
"The Quick Reference has the answer"
"This is a common pattern"
"I'll check the guide if this doesn't work"
"My knowledge is sufficient"

All of these mean: Search migration-guide.md FIRST.

Reference Documentation

The migration-guide.md file contains Apple's complete migration documentation (25 bundled files, 3700+ lines):

Topic	Search Pattern
Common errors	`FILE: Guide.docc/CommonProblems.md`
Data race safety	`FILE: Guide.docc/DataRaceSafety.md`
Incremental adoption	`FILE: Guide.docc/IncrementalAdoption.md`
Swift 6 mode	`FILE: Guide.docc/Swift6Mode.md`
Complete checking	`FILE: Guide.docc/CompleteChecking.md`
Sendable examples	`FILE: Sources/Examples/ConformanceMismatches.swift`
Global variable patterns	`FILE: Sources/Examples/Globals.swift`

To find specific content: grep -n "pattern" migration-guide.md