Skip to content

Reorder and tighten the unreleased changelog#487

Merged
alistair3149 merged 1 commit into
masterfrom
worktree-changelog-order
Jul 23, 2026
Merged

Reorder and tighten the unreleased changelog#487
alistair3149 merged 1 commit into
masterfrom
worktree-changelog-order

Conversation

@alistair3149

Copy link
Copy Markdown
Member

Two passes over the [Unreleased] section: reorder by audience, then tighten the prose. No entry was added or removed, and no factual claim changed.

Reorder

Of the eight Added entries, six applied only to deployments running the hosted OAuth proxy, yet they led the section. Entries that reach every user now come first in each subsection:

  • Added — per-wiki edit attribution, then plugin installs, then the proxy entries, then metrics.
  • Changed — the npx -y change, then proxy sign-in persistence.
  • Fixed — the spurious JSON warning and the port-bind message, then the four proxy fixes.

Keep a Changelog section order is unchanged. Breaking changes stays first even though its single entry is proxy-specific, since a breaking change should stay prominent regardless of who it reaches.

Writing pass

Against the CHANGELOG genre in docs/documentation-conventions.md (reader: users deciding whether to upgrade; observable behaviour, no internal jargon):

  • Removed all eight em-dash asides. Several entries buried their substance in a dash clause, most notably the metrics entry, which interrupted itself to list four series names. The names now sit in their own sentence after the benefit.
  • Each entry leads with the observable change rather than the mechanism.
  • Three proxy entries gained the Hosted OAuth proxy: prefix their siblings already carried (the consent page, IPv6 loopback, and the loopback-variable-port fix), so an entry's audience is visible without reading it in full. Each was verified proxy-specific against the source rather than assumed.
  • Fixed a dangling "This", a stranded preposition, and a doubled "instead".

Verification

  • 18 entries before and after; a sorted diff of all entries confirms none was dropped or duplicated.
  • Every identifier, environment variable, metric name, file path, RFC number and quoted error string from the original is still present.
  • A semantic review paired each rewritten entry with its original to check for lost, weakened, or newly-asserted claims. It confirmed the breaking-change warning is intact and verified the three new prefixes against the code, then raised seven precision points, all of which are fixed here. Two were regressions the rewrite had introduced: "on the default wiki" (you set an environment variable for a wiki, and the original wording matched the runtime error string verbatim), and "whether the port is in use or permission is denied", which read as exhaustive when handleListenError has a third branch.

🤖 Generated with Claude Code

Entries that affect every user now come before the hosted OAuth proxy
ones, which only reach deployments running that proxy. Section order is
unchanged, and Breaking changes stays first.

The prose pass removes em-dash asides, leads each entry with the
observable change rather than the mechanism, and gives the three proxy
entries that did not identify their scope the same prefix as their
siblings.
@alistair3149
alistair3149 merged commit 923601c into master Jul 23, 2026
1 check passed
@alistair3149
alistair3149 deleted the worktree-changelog-order branch July 23, 2026 23:51
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