scripts/style-manifest-swift.txt is a gradual-rollout exemption list, and it should only ever shrink. This issue is the scheduled sweep that pays down what it still exempts, so the exemption does not quietly become permanent.
Pattern and rationale: OCCTMCP#179, landed as OCCTMCP#181. Ecosystem-level context in ecosystem#41, which mirrors the migration carve-out into the rollout mechanism so other repos inherit it rather than rediscovering the collision on their own first kernel major.
Do not start this without a plan discussion first. It is filed to record the debt, not to be picked up blind.
This is roughly ten times the size of the OCCTMCP sweep that motivated the pattern, in the kernel repo where a mechanical reformat has the widest blast radius. Two Pass 3 refactor PRs are open at filing time (#958, #959), and a 197-file reformat would conflict with any in-flight work across most of Sources/.
Realistic options, none of them obviously right:
- Split by directory into several PRs, each independently reviewable, scheduled around the Pass 3 work rather than against it.
- Sweep opportunistically, letting the existing "if you touch it, you fix it" rule drain the manifest over time, and accept that 197 entries will take a while.
- One big sweep in a quiet window, which is cheapest in total effort and worst for anything already on a branch.
The 677 hand-written doc summaries are the real cost and do not shrink under any of the three.
Measured 2026-08-19, against origin/main
|
|
| Manifest entries |
197 |
| Stale entries (listed, file missing) |
0 |
swift-format format diff |
~10,903 lines |
Total --strict diagnostics |
6,490 |
Of those, BeginDocumentationCommentWithOneLineSummary |
677 |
Top rule counts are Indentation, LineLength and AddLines, all mechanical.
The 677 doc-comment summaries are the only part that is not mechanical. swift-format format cannot invent a one-line summary for a symbol; each needs a human decision about what the thing actually does. That is the real cost of this issue, and it does not shrink by deferring.
Re-measure fresh before starting rather than trusting these numbers, per the ecosystem's code-structure policy. Other PRs may touch or clear manifest entries between now and whenever this is picked up.
Work
swift-format format each in-scope file. Mechanical.
- Hand-write the doc-comment one-line summaries
swift-format format cannot generate.
swift-format lint --strict and swiftlint lint --strict clean on every swept file.
- Remove each swept file from
scripts/style-manifest-swift.txt.
swift build && swift build --build-tests && swift test green. A formatting-only change should be behaviour-neutral, but that needs verifying rather than assuming: swift build alone does not compile test targets.
Not in scope
Do not fix bugs, rename anything, or change behaviour. If the reformat surfaces something that looks wrong, file it separately and leave it alone here. A sweep that also changes behaviour is unreviewable, which is the whole reason the migration carve-out exists.
scripts/style-manifest-swift.txtis a gradual-rollout exemption list, and it should only ever shrink. This issue is the scheduled sweep that pays down what it still exempts, so the exemption does not quietly become permanent.Pattern and rationale: OCCTMCP#179, landed as OCCTMCP#181. Ecosystem-level context in ecosystem#41, which mirrors the migration carve-out into the rollout mechanism so other repos inherit it rather than rediscovering the collision on their own first kernel major.
Do not start this without a plan discussion first. It is filed to record the debt, not to be picked up blind.
This is roughly ten times the size of the OCCTMCP sweep that motivated the pattern, in the kernel repo where a mechanical reformat has the widest blast radius. Two Pass 3 refactor PRs are open at filing time (#958, #959), and a 197-file reformat would conflict with any in-flight work across most of
Sources/.Realistic options, none of them obviously right:
The 677 hand-written doc summaries are the real cost and do not shrink under any of the three.
Measured 2026-08-19, against
origin/mainswift-format formatdiff--strictdiagnosticsBeginDocumentationCommentWithOneLineSummaryTop rule counts are
Indentation,LineLengthandAddLines, all mechanical.The 677 doc-comment summaries are the only part that is not mechanical.
swift-format formatcannot invent a one-line summary for a symbol; each needs a human decision about what the thing actually does. That is the real cost of this issue, and it does not shrink by deferring.Re-measure fresh before starting rather than trusting these numbers, per the ecosystem's code-structure policy. Other PRs may touch or clear manifest entries between now and whenever this is picked up.
Work
swift-format formateach in-scope file. Mechanical.swift-format formatcannot generate.swift-format lint --strictandswiftlint lint --strictclean on every swept file.scripts/style-manifest-swift.txt.swift build && swift build --build-tests && swift testgreen. A formatting-only change should be behaviour-neutral, but that needs verifying rather than assuming:swift buildalone does not compile test targets.Not in scope
Do not fix bugs, rename anything, or change behaviour. If the reformat surfaces something that looks wrong, file it separately and leave it alone here. A sweep that also changes behaviour is unreviewable, which is the whole reason the migration carve-out exists.