docs(changelog): streamline 0.11.0 notes for end users#80
Conversation
Drop deep root-cause analysis (byte-offset / bit-level rationale, Swift source line references, CI workflow internals) that only matters to contributors, and reorganize around user-facing impact: - Add "What this unlocks" summarizing the concrete capabilities the three fixes restore (generic introspection, cross-module binaries, deterministic parallel tests). - Replace the long "Dependencies" paragraph with an "Upgrading" section containing a before/after snippet for the swift-demangling 0.3.0 async migration. - Drop "CI", "Docs", and "Known Issues" sections. Release notes on GitHub already synced to this content.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request refactors the version 0.11.0 changelog to be more concise, adding a 'What this unlocks' section and an 'Upgrading' guide for the swift-demangling 0.3.0 async API migration. Feedback indicates that the claim regarding all internal call sites being migrated is inaccurate, as several locations in the codebase still use synchronous versions of the demangling APIs.
|
|
||
| - Corrected MachOKit version in the `0.10.0` notes: `0.49.100` (based on upstream `0.49.0`), not `0.47.100`. | ||
| - `KNOWN_ISSUES.md` annotated recent CI runs that reproduced the `SymbolIndexStore.demangledNode` data race so its flaky, parallel-harness-only nature was easier to recognize during triage. A follow-up will move that entry to the "fixed" section once `0.11.0` has been green across a few CI runs. | ||
| No changes required for `MachOFile.Swift.*` section APIs, `SwiftDump`, `SwiftInterface`, or `SwiftInspection` — all internal call sites are already migrated. |
There was a problem hiding this comment.
The statement that "all internal call sites are already migrated" appears to be inaccurate. Several call sites in the codebase still use demangleAsNode and Node.print without await, such as in Sources/MachOSymbols/SymbolIndexStore.swift (lines 249, 397, 446, 597) and Tests/SwiftInspectionTests/MultiPayloadEnumTests.swift (lines 30, 149). If these APIs are indeed async in version 0.3.0, these call sites should be updated to ensure the project compiles and behaves correctly, or the changelog should be clarified to reflect the current state of the migration.
There was a problem hiding this comment.
Pull request overview
This PR refines the 0.11.0 changelog entry to be more end-user oriented by summarizing user-visible outcomes, simplifying technical root-cause detail, and providing a focused upgrade note around the swift-demangling dependency change.
Changes:
- Rewrites Highlights and adds What this unlocks to emphasize user-facing impact.
- Collapses detailed bug-fix narratives into concise bullets and streamlines the Library section.
- Replaces the old dependency/CI/docs/known-issues content with a new Upgrading section and an example snippet.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| `swift-demangling` minimum is now `0.3.0`. `Node.print`, `demangleAsNode`, and `mangleAsString` are now async. Call sites need `await`: | ||
|
|
||
| - Added `GenericSpecializationTests`, `MultiPayloadEnumTests`, and `MetadataReaderDemanglingTests` to the macOS matrix filter so future regressions in the generic-context dispatch path or the section reader path surface in CI instead of as local crashes. `GenericSpecializerAPITests` was folded into `GenericSpecializationTests`, and the corresponding filter entry removed. | ||
| - `Sources/swift-section/Version.swift` is the single source of truth for the CLI version: | ||
| - `release.yml` no longer injects the version via heredoc; it fails a tagged release when `BundledVersion.value != github.ref_name`. | ||
| - A new `version-check.yml` workflow runs on every push to `main` and every PR, and fails when `Changelogs/<BundledVersion.value>.md` does not exist. | ||
| - The extraction shell is whitespace-tolerant and guards `grep`'s exit status so formatter changes cannot silently break the check. | ||
| - Source builds (including Homebrew's source path) now report the correct version without depending on CI injection. | ||
| ```swift |
| 1. Fixes the parallel-test `SymbolIndexStore` data race (previously tracked in `KNOWN_ISSUES.md`) that surfaced intermittently as SIGSEGV or as `.invalidContextDescriptor` failures on CI. | ||
| 2. Swift section readers now mirror the ABI in `swift/include/swift/ABI/Metadata.h` — `__swift5_types` / `__swift5_protos` indirect entries are read correctly (previously misread as direct pointers, which on cross-module binaries produced garbage context-descriptor kinds). | ||
| 3. Carries forward the generic-context dispatch signal-11 fix and the `swift-demangling` 0.3.0 async-API migration originally planned for `0.10.1`. | ||
| - **Generic type introspection** — `GenericSpecializer`, `EnumLayoutCalculator`, and any code iterating `typeContextDescriptors` of generic struct / class / enum types is now crash-free. Previously surfaced as `EXC_BAD_ACCESS` from reading the generic header at the wrong offset. |
Summary
Post-release cleanup of
Changelogs/0.11.0.md. The original notes leaned heavily on contributor-oriented root-cause detail (byte-offset rationale, Swift source line references, CI workflow internals) that end users don't need. This reorganizes around user-facing impact.swift-demangling0.3.0 async migration.Net change: +23 / −42.
The GitHub release at https://github.com/MxIris-Reverse-Engineering/MachOSwiftSection/releases/tag/0.11.0 is already synced to this content.
Test plan
Changelogs/0.11.0.mdon GitHub and confirm formatting (headings, code block, links) looks right