Skip to content

docs: make the 1.0.0 changelog readable rather than dense - #503

Merged
fjmorant merged 2 commits into
masterfrom
docs/changelog-readability
Sep 26, 2026
Merged

fjmorant merged 2 commits into
masterfrom
docs/changelog-readability

Conversation

@fjmorant

Copy link
Copy Markdown
Owner

The live v1.0.0 release is already updated with the result. This PR brings CHANGELOG.md in line, since #502 made the release be the CHANGELOG entry — which means how the entry reads is how the release reads.

What was wrong

The 1.0.0 entry was a wall of text:

  • tight lists — no blank lines between items, so GitHub renders them without paragraph spacing and everything runs together
  • bullets running to eight lines, several in a row
  • two bullets carrying three paragraphs each (INode, listProps), buried mid-list with no heading to find them by
  • nothing to anchor the eye — no tables, no code blocks, no subheadings between the section headers

141 lines of unbroken prose bullets.

Same facts, restructured

Change Why
The two multi-paragraph bullets become #### subsections INode and listProps are navigable instead of buried
An At a glance table near the top the four numbers most readers actually want, before any prose
listProps merge order becomes a table it was a three-way precedence rule written as a paragraph
Both upgrade steps become code blocks shorter than describing the edit, and harder to misread
Lists are loose throughout items separate instead of running together

Now 181 lines with 2 tables, 2 code blocks and 4 subsections, so the section headers aren't the only structure.

Nothing lost

I grepped the rewritten section for every term the original used — 20,000-level, object-hash, IRenderedNode, listProps, TOP_LEVEL, paddingLeftIncrement, node-view, keyExtractor, IRow, initialNumToRender, _internalId, readonly INode — all still present, and the code fences and table header rows are balanced.

Also fixed a stray blank line that had made one item of the Fixed list render as a separate list.

Note for next time

prettier-check only covers src/**/*.{ts,tsx}, so Markdown is unformatted and hand-aligned tables survive as written. That is what we want here, but worth knowing the CHANGELOG has no automated formatting behind it.

🤖 Generated with Claude Code

Now that the GitHub release is the CHANGELOG entry, how the entry reads is how
the release reads, and the 1.0.0 entry was a wall of text: tight lists with no
blank lines between items, several bullets running to eight lines, and two that
carried three paragraphs each. Nothing anchored the eye — no tables, no code
blocks, no subheadings between the section headers.

Same facts, restructured. The two multi-paragraph bullets become subsections,
so INode and listProps are navigable rather than buried mid-list. An at-a-glance
table near the top carries the four numbers most readers want. The merge order
for listProps becomes a table, since it was a three-way precedence rule written
as prose. Both upgrade steps become code blocks showing the before and after,
which is shorter than describing the edit and harder to misread. Lists are loose
throughout, so items separate instead of running together.

Checked that nothing was lost by grepping the rewritten section for every term
the original used, and that the code fences and tables are balanced. The live
v1.0.0 release has been updated with the result.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@fjmorant
fjmorant merged commit d1b8940 into master Sep 26, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant