Skip to content

docs(changelog,contributing): revise the 1.0.0 entries and document changelog style#3

Merged
jcardozo-eth merged 6 commits into
mainfrom
docs/changelog-style-1.0.0
Jul 9, 2026
Merged

docs(changelog,contributing): revise the 1.0.0 entries and document changelog style#3
jcardozo-eth merged 6 commits into
mainfrom
docs/changelog-style-1.0.0

Conversation

@jcardozo-eth

@jcardozo-eth jcardozo-eth commented Jul 9, 2026

Copy link
Copy Markdown
Member

Two documentation-only changes that belong together: fix the 1.0.0 changelog, and write down the guidance for keeping it that way.

  1. Revise the published ## [1.0.0] CHANGELOG section: reflow each entry onto a single line, trim over-explanation, reframe the token entries as a mechanism (not a capability the module enforces), state the config-reload behaviour accurately, and a few minor wording fixes.
  2. Add a ## Changelog section to CONTRIBUTING that codifies what earns an entry and how to write it, so the changelog stays this way.

No code, no behaviour change. No new release: the v1.0.0 tag and its GitHub Release are untouched (the published notes are re-synced to this text after merge).

Reasoning

Publishing 1.0.0 turned the changelog into the GitHub Release notes, which surfaced problems worth fixing at the source:

  • Rendering: entries were hard-wrapped, so GitHub rendered them with mid-sentence line breaks. Single-line entries fix this.
  • Over-explanation: several entries carried justifying tails and asides ("so the module stays out of the way…", "the module is never edited to onboard a host…") that belong in the README, not the release notes.
  • Accuracy: a couple of entries over- or mis-stated things, framing a mechanism as a guarantee the module enforces, or implying a behaviour was standalone-only when it applies in any mode.
  • No written rule: nothing captured how an entry should read, so the drift would recur. The new CONTRIBUTING section writes it down.

Why this is exceptional, but still the right call now

Editing an already-released ## [x.y.z] section is normally avoided: Keep a Changelog treats released sections as historical, and rewriting them can mislead anyone who already acted on them. We are doing it deliberately, and it is justified here:

  • No downstream consumers yet: v1.0.0 was released only hours ago.
  • Meaning is unchanged: every edit tightens or corrects wording; no entry gains or loses a claim about behaviour.
  • It sets a clean baseline that matches the rules we are codifying, before more entries accrue under the old habits.

Accepted implications

  • The ## [1.0.0] section on main will differ from the CHANGELOG snapshot inside the immutable v1.0.0 tag. Expected and harmless; the tag is history, main is current.
  • The published v1.0.0 Release notes will be re-synced to this text after merge, with gh release edit (editing the existing release in place; no new release, no new tag).

Result

The tightened ## [1.0.0] now conforms to the newly-documented CONTRIBUTING rules: the guidance and the example it governs agree, a clean starting point.

@jcardozo-eth jcardozo-eth force-pushed the docs/changelog-style-1.0.0 branch from 37e1ee9 to db5529d Compare July 9, 2026 14:45
@jcardozo-eth jcardozo-eth self-assigned this Jul 9, 2026
@jcardozo-eth jcardozo-eth merged commit ae9357a into main Jul 9, 2026
3 checks passed
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