Skip to content

Rewrite the Unreleased changelog for game developers - #201

Closed
mmacy wants to merge 3 commits into
mainfrom
chunk/prose-changelog
Closed

mmacy wants to merge 3 commits into
mainfrom
chunk/prose-changelog

Conversation

@mmacy

@mmacy mmacy commented Oct 31, 2026

Copy link
Copy Markdown
Owner

The Unreleased section had grown dense, hard-to-read bullets over the backlog run. This rewrites it for a game developer upgrading from 2.0.1.

What changed

  • Each bullet opens with what changed and what the developer must do, if anything. Several cases become nested lists.
  • Each osrlib term is defined once, where it first appears, or linked to the API member or docs page that defines it.
  • Four claims were corrected against the code: the wandering-check interval during a rest, a fourth command that 2.0.1 accepted and this release refuses, sleep's no-area rule, and replacement_too_far.
  • Cut: the notes on which golden test files changed.

How it was checked

A fact checker compared the old and new text against the code, and found no dropped or wrong facts. Then two rounds of readers with no project context read every bullet one at a time and summarized each in their own words. I fixed what they misread or couldn't answer, until their summaries matched the facts.

The DungeonState.door bullet will change in a follow-up code fix, because of a door defect found during this pass.

https://claude.ai/code/session_01V7ErtnsmhaP7aLwcfmzohD

mmacy added 3 commits October 30, 2026 17:13
Each bullet now leads with what changed and what a developer upgrading
from 2.0.1 has to do, with the detail in short sentences and nested
lists for bullets that cover several cases. Every link, code span,
issue number, and SRD quotation is unchanged.

Three claims are corrected against the code: a rest checks for
wandering monsters on the level's interval, not every turn; a 2.0.1
log that declares a close move or an area spell at a fled group no
longer replays; and only sleep, not every hd_budget mode, ignores the
area footprint when aimed at a group. Mentions of golden files are cut.

Claude-Session: https://claude.ai/code/session_01V7ErtnsmhaP7aLwcfmzohD
Three cold readers found osrlib terms used without a definition, steps
a developer must take left implicit, and dangling references between
entries. Each term is now defined once where it first appears, by a
clause or a link to the API member or docs page that defines it. Each
entry that needs a change in a game says so in its first sentences.
The replay entry now says how to reproduce a 2.0.1 game, and the
withdrawal entry lists its four refusal codes.

Claude-Session: https://claude.ai/code/session_01V7ErtnsmhaP7aLwcfmzohD
Each fix answers a question two fresh readers still had. The rest and
routine-label entries now state the behavior change and the default.
The withdrawal entry names its three new codes. The petrified-party
entry is split into cases, with the recovery path marked optional.
The replay entry says how to replay under 2.0.1. Several Fixed entries
now give the numbers and defaults the readers asked for. The
DungeonState.door entry is left for the lead's door fix.

Claude-Session: https://claude.ai/code/session_01V7ErtnsmhaP7aLwcfmzohD
@mmacy

mmacy commented Oct 31, 2026

Copy link
Copy Markdown
Owner Author

Replaced by a pull request from docs/unreleased-changelog, whose commit messages avoid the jargon the maintainer has asked me to drop. The changes are identical.

@mmacy mmacy closed this Oct 31, 2026
@mmacy
mmacy deleted the chunk/prose-changelog branch October 31, 2026 00:24
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