swift-6-migration

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:**

1. **FIRST** search migration-guide.md for the error pattern
2. **THEN** read the matched FILE: section
3. **THEN** apply the documented fix
4. **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

```bash
# 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