docs: Add Swift 6.3 compatibility limitations to README

[doozMen]

No description provided.

[doozMen]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• ci: Add Swift version matrix for 6.0, 6.2, and 6.3 testing #10
• docs: Add Swift 6.3 compatibility limitations to README #9 👈 (View in Graphite)
• fix: Add compile-time warning for disabled CloudKit on Swift 6.3+ #8
• workaround for compiler crash - no cloudkit for swift 6.3 at the moment #7
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Swift 6.3 Compatibility Documentation

Thanks for adding this important documentation! This PR clearly communicates the Swift 6.3 limitations to users. Here's my review:

✅ Strengths

1. Clear Communication: The warning at the top immediately alerts users to compatibility issues
2. Good Structure: Well-organized sections (Affected Features, Workaround, Timeline)
3. Proper References: Links to issue Swift 6.3-dev compiler crashes - workarounds applied #2 for context
4. Positioning: Placed early in the README (right after badges) where users will see it

📝 Suggestions for Improvement

1. Table of Contents Anchor Link (README.md:11)

The TOC entry uses #Swift-63-Compatibility but GitHub's markdown anchor format typically lowercases all text and uses hyphens. The correct anchor should be:

  * [Swift 6.3 Compatibility](#swift-63-compatibility)

You can verify by clicking the link after merging - if it doesn't work, this is likely why.

2. Duplicate "Overview" Entry (README.md:13,17)

There are two "Overview" entries in the table of contents (lines 13 and 17). This appears to be a pre-existing issue, but worth cleaning up.

3. Consider Version Specificity

The section title says "Swift 6.3" but the content refers to "Swift 6.3-dev" and "Swift 6.3+". Consider clarifying:

• Is this only Swift 6.3-dev (development snapshots)?
• Or does it affect all Swift 6.3+ versions including stable releases?

The section title might be more accurate as "Swift 6.3-dev Compatibility" if it's only development versions.

4. Timeline Section Clarity

The "Timeline" section states these will be removed "once the Swift compiler bugs are fixed." Consider adding:

• Whether this is being tracked in the Swift bug tracker (if you've filed a report)
• Or mention that you're monitoring the situation as noted in issue Swift 6.3-dev compiler crashes - workarounds applied #2

🔍 Code Quality Assessment

Documentation Quality: ✅ Good

• Clear, concise writing
• Good use of formatting (bold for "Important")
• Appropriate level of technical detail

Accuracy: ✅ Good

• Consistent with issue Swift 6.3-dev compiler crashes - workarounds applied #2
• Correctly identifies affected features

User Experience: ✅ Good

• Provides actionable workaround
• Sets expectations with timeline

🎯 Recommendations

Priority: Medium - Fix the TOC anchor link to ensure navigation works correctly.

Optional: Consider adding a note about what "regularly" means in "We test against new Swift snapshots regularly" - weekly? monthly? This helps set user expectations.

Summary

This is a valuable documentation addition that will help users understand the current limitations. The content is well-written and appropriately positioned. The main issue is the TOC anchor link format which should be fixed to ensure proper navigation.

Overall Assessment: Approve with minor revisions suggested ✅

---

🤖 Generated with Claude Code

[graphite-app]

The table of contents anchor link #Swift-63-Compatibility won't correctly navigate to the section. GitHub markdown auto-generates anchors from headers in lowercase with hyphens. The anchor should be:

* [Swift 6.3 Compatibility](#swift-63-compatibility)

The current link with capital letters will result in a broken navigation link when users click on it in the table of contents.

Suggested change

	* [Swift 6.3 Compatibility](#Swift-63-Compatibility)
	* [Swift 6.3 Compatibility](#swift-63-compatibility)

Spotted by Graphite Agent



Is this helpful? React 👍 or 👎 to let us know.