docs: explain why iOS 13+ is required instead of iOS 12

[Copilot]

Users were confused why the minimum deployment target is iOS 13 given that Network.framework shipped in iOS 12.

Changes

• README.md — Added ### Why iOS 13+ instead of iOS 12? subsection under Requirements, directly before Installation, covering:
  • Comparison table: NWConnection stability, continuous read loop reliability, and Swift runtime embedding across iOS 12 vs 13+
  • Four key details: Network.framework maturity, read-loop edge-case fixes, Swift-runtime-in-OS, and 2019 platform alignment
  • Note for users who need iOS 12 support (compile-time workaround + caveats)

Original prompt

Problem

The README's Requirements section currently only lists the minimum platform versions (iOS 13.0+ / macOS 10.15+ etc.) without explaining why iOS 13 is the minimum instead of iOS 12, given that Network.framework was introduced in iOS 12. This has caused user confusion (see discussion in tasks).

Requested Change

Add a new subsection under Requirements (line 20-24 in README.md) titled "Why iOS 13+ (not iOS 12)?" that explains the rationale. The new section should be inserted immediately after the existing requirements list and before the ## Installation section.

Content to add

After line 24 (after - Xcode 15+ (for Objective-C version)), insert the following:

### Why iOS 13+ instead of iOS 12?

Although `Network.framework` was introduced in iOS 12 (WWDC 2018), this library requires **iOS 13+** for the following reasons:

| Aspect | iOS 12 | iOS 13+ |
|--------|--------|---------|
| Network.framework availability | ✅ Available | ✅ Available |
| Stability & bug fixes | ❌ Known issues with `NWConnection` callbacks and memory leaks | ✅ Major fixes shipped |
| Continuous read loop reliability | ⚠️ Edge-case bugs in `NWConnection.receive()` under high-frequency reads | ✅ Stable |
| Swift runtime | ❌ Must be embedded in app bundle | ✅ Built into the OS |

**Key details:**

1. **Network.framework maturity** — Apple significantly improved `NWConnection` reliability in iOS 13, fixing known issues with callback delivery and memory management that existed in the iOS 12 initial release.
2. **Continuous read loop stability** — This library's core architecture uses a high-frequency continuous read loop (`receive()` → buffer → dequeue → `receive()`). This pattern triggers edge-case bugs on iOS 12 that were resolved in iOS 13.
3. **Swift runtime built-in** — Starting from iOS 13, the Swift runtime is bundled with the OS, which reduces app binary size and avoids runtime compatibility issues.
4. **Platform version alignment** — iOS 13 / macOS 10.15 / tvOS 13 / watchOS 6 are all from the same 2019 release cycle, ensuring a consistent and well-tested foundation across all Apple platforms.

> **Note:** If you absolutely need iOS 12 support, changing `.iOS(.v13)` to `.iOS(.v12)` in `Package.swift` will compile, but thorough testing on iOS 12 devices is strongly recommended — especially for long-lived connections and high-frequency read/write scenarios.

Files to modify

• README.md — Insert the new subsection between the existing Requirements list and the Installation section.

Acceptance criteria

• The new "Why iOS 13+ instead of iOS 12?" subsection appears in README.md under Requirements
• The existing content and formatting of README.md is preserved
• The markdown table renders correctly

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR adds documentation explaining why NWAsyncSocket requires iOS 13+ instead of iOS 12, despite Network.framework being available in iOS 12. The addition addresses user confusion by providing technical justification for the minimum deployment target decision.

Changes:

• Added a "Why iOS 13+ instead of iOS 12?" subsection under Requirements in README.md with a comparison table and detailed technical explanations

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.