Skip to content

Sweep the code-style manifest into full compliance #960

Description

@gsdali

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:

  1. Split by directory into several PRs, each independently reviewable, scheduled around the Pass 3 work rather than against it.
  2. 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.
  3. 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

  1. swift-format format each in-scope file. Mechanical.
  2. Hand-write the doc-comment one-line summaries swift-format format cannot generate.
  3. swift-format lint --strict and swiftlint lint --strict clean on every swept file.
  4. Remove each swept file from scripts/style-manifest-swift.txt.
  5. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions