Skip to content

docs: sweep CHANGELOG for the documentation style check - #366

Merged
remyluslosius merged 1 commit into
mainfrom
docs/sweep-changelog-style
Jul 26, 2026
Merged

docs: sweep CHANGELOG for the documentation style check#366
remyluslosius merged 1 commit into
mainfrom
docs/sweep-changelog-style

Conversation

@remyluslosius

Copy link
Copy Markdown
Contributor

CHANGELOG.md carried 172 findings against the Doc style check added in #364.
The check scans changed files whole, so the next PR to touch this file would have
inherited the cleanup mid-release. Clearing it now keeps that off the release
path.

Please read the diff rather than merging on green. This rewrites a public
historical record, and no gate can tell you whether the prose still reads well.

What changed

  • 176 em dashes removed, resolved by what each clause was doing rather than
    by one substitution: paired asides became parentheses (5), bold lead-ins took a
    colon (26), appositives a comma (105), independent clauses a semicolon, and
    four became sentence breaks.
  • All 23 version headings moved to ## vX.Y.Z (YYYY-MM-DD), matching the
    format CONTRIBUTING adopted in docs: align CONTRIBUTING with the shared git and GitHub standard #365. docs_check.sh validates that a heading
    carries an ISO date, not which separator precedes it, so both forms pass and no
    gate changed.
  • "behavior harness" is now "check-behavior suite", citing
    rule_behavior_harness_test.go in code font. The checker reads harness as
    hype; here it is the shipped artifact's name. Putting the real name in a code
    span keeps the record accurate in a context the checker exempts, rather than
    suppressing the finding or renaming history. The false positive is filed
    against the shared tool.

Why the first pass was not enough

A pattern-aware transform still produced eleven comma splices, all from the
same cause: an em dash ending a line almost always introduces an explanation, so
a comma reads as a run-on. Examples now fixed:

  • This is the honest result, those rules do not apply becomes a colon.
  • The old path had no equivalent, it relied on the scheduler becomes a colon.
  • pwquality difok. CIS >= 2 had a period inserted inside a parenthetical.

Verification that content survived

After normalising punctuation, the entire file differs from its previous state by
exactly the two intended word changes above. Nothing else moved.

before after
PR/issue references 75 75
Markdown links 2 2
Bold spans 153 153
Version headings 23 23

make docs-check and make docs-style both pass.

CHANGELOG carried 172 style findings, so the next PR to touch it would have
inherited the cleanup mid-release. Clearing it now keeps that off the release
path.

Removes 176 em dashes, resolved by what each clause was doing rather than by one
substitution: paired asides became parentheses, bold lead-ins took a colon,
appositives a comma, and independent clauses a semicolon or a sentence break. A
first pass produced eleven comma splices where an em dash had ended a line
introducing an explanation; those are colons now.

Migrates all 23 version headings to the parenthesised date form CONTRIBUTING
adopted in #365. docs_check validates that a heading carries an ISO date, not
which separator precedes it, so both forms pass and no gate changed.

Renames "behavior harness" to "check-behavior suite" and cites
rule_behavior_harness_test.go in code font. The checker reads "harness" as hype;
here it is the shipped artifact's name, so the name stays, in a span the checker
exempts. The false positive is filed against the shared tool.

Verified content-preserving: after normalising punctuation, the whole file
differs by exactly the two intended word changes above. Reference counts are
unchanged at 75 PR links, 2 markdown links, and 153 bold spans.
@remyluslosius
remyluslosius merged commit 29a44da into main Jul 26, 2026
21 checks passed
@remyluslosius
remyluslosius deleted the docs/sweep-changelog-style branch July 26, 2026 14:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant