docs: split the README into focused documents and write the 3.1.0 notes - #87
Merged
Conversation
The README had grown to just over 1000 lines, which buries the two things a visitor actually needs first - what this is and how to install it - under a full API reference, two release-note sections, a migration guide and a troubleshooting appendix. Split by audience: | file | contents | |---|---| | README.md | pitch, features, quick start, install, links | | docs/API.md | initializers, modifiers, utilities | | docs/ADVANCED.md | custom fonts, theming, media, performance, examples | | docs/TROUBLESHOOTING.md | common issues, platform notes | | docs/MIGRATION.md | upgrading from v2.x | | CHANGELOG.md | release notes, newest first | | CONTRIBUTING.md | moved to the path GitHub surfaces in its UI | README goes from 1079 lines to 161. Nothing was dropped: the only prose removed is the second Quick Start example, folded into the first, and the table of contents, replaced by the documentation table. Also documents 3.1.0 itself - the fixes, the errors that now actually fire, the interpolated CSS builders, and a table of the nine new deprecations with their replacements. Version pins in the install instructions move to 3.1.0, and the sample app README lists the new behaviour worth testing.
Re-verified both entries by reading the dependency manifest in each repository rather than trusting a search index: - IBM/mac-ibm-notifications - Notification Agent.xcodeproj/project.pbxproj - AudioBooth/AudioBooth - AudioBooth.xcodeproj/project.pbxproj Both are unarchived and were pushed to within the last two months. Reformatted as a table and made the disclaimer state the actual evidence - each project's public manifest - and that no endorsement is implied in either direction. Star counts are deliberately left out, since they would go stale in the file. Note for anyone looking to extend this list: GitHub's dependency graph reports zero dependents for this repository because it does not index Swift package manifests, and code search misses both entries above, so neither is a reliable source on its own.
NuPlay
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The README had grown to just over 1000 lines. The two things a visitor needs first - what this is and how to install it - were buried under a full API reference, two release-note sections, a migration guide and a troubleshooting appendix.
Changes
Split by audience:
README.mddocs/API.mddocs/ADVANCED.mddocs/TROUBLESHOOTING.mddocs/MIGRATION.mdCHANGELOG.mdCONTRIBUTING.mdNothing was dropped. The only prose removed is the second Quick Start example, folded into the first, and the table of contents, replaced by a documentation table. Verified by extracting every ```swift block from the old README and checking each one survives somewhere in the new set - 34 blocks in, 37 out, and the three that do not match verbatim are the two Quick Start examples that were merged and the
Package.swiftblock whose version pin changed.3.1.0 release notes
CHANGELOG.mdnow documents this release rather than the README accumulating another "What's New" section:<details>not expanding, Dynamic Type discardingfontTypeisColorsImportantcalled out since it silently did nothingVersion pins in the install instructions move to
3.1.0, and the sample app README lists the new behaviour worth testing.Used By
Both entries re-verified by reading the dependency manifest in each repository:
IBM/mac-ibm-notifications-Notification Agent.xcodeproj/project.pbxprojAudioBooth/AudioBooth-AudioBooth.xcodeproj/project.pbxprojWorth recording for whoever extends that list: GitHub's dependency graph reports zero dependents for this repository because it does not index Swift package manifests, and code search misses both entries above. Neither is a reliable source on its own.