[Docs] Cut a 0.1.0 section from the 52,000-word Unreleased changelog #609

New issue

Closed

opened 2026-07-22 16:19:53 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:19:53 +00:00

Owner

Found in the pre-publication documentation review.

Measurement: CHANGELOG.md is 4,903 lines / 330 KB — the largest public file in the project. Under ## [Unreleased]: 52,090 words in 455 bullets, averaging 114 words per changelog entry (Keep a Changelog entries are typically 5-20). There are exactly two ## headings in the file, but beneath them the same subheadings repeat: 9× ### Added, 9× ### Fixed, 7× ### Changed, 2× ### Security — all within one [Unreleased]. That is no longer a Keep a Changelog structure; it is a reverse diary.

grep -rn "0\.1\.0" finds zero hits in CHANGELOG.md, while docs/FILE_FORMAT.md writes "Until 0.1.0…" / "as of 0.1.0" in thirteen places as though that version already exists.

Why this matters now: the changelog is the second file an interested developer opens. Anyone wanting to know what is in 0.1.0 finds no 0.1.0 heading and 52,000 words of unsorted work — the "nothing is finished" impression you most want to avoid.

Proposal: put one ## [0.1.0] — 2026-xx-xx heading above the existing content and move the essays to a ## Development log below it or to a separate file, leaving roughly 40 one-line entries under 0.1.0. Nothing needs to be thrown away; it just needs to stop being the first 4,900 lines. Write the new 0.1.0 heading and its summary in English, so the first screen matches the language of the README.

Found in the pre-publication documentation review. **Measurement:** `CHANGELOG.md` is 4,903 lines / 330 KB — the largest public file in the project. Under `## [Unreleased]`: **52,090 words in 455 bullets**, averaging **114 words per changelog entry** (Keep a Changelog entries are typically 5-20). There are exactly two `## ` headings in the file, but beneath them the same subheadings repeat: 9× `### Added`, 9× `### Fixed`, 7× `### Changed`, 2× `### Security` — all within one `[Unreleased]`. That is no longer a Keep a Changelog structure; it is a reverse diary. `grep -rn "0\.1\.0"` finds zero hits in `CHANGELOG.md`, while `docs/FILE_FORMAT.md` writes "Until 0.1.0…" / "as of 0.1.0" in thirteen places as though that version already exists. **Why this matters now:** the changelog is the second file an interested developer opens. Anyone wanting to know what is in 0.1.0 finds no 0.1.0 heading and 52,000 words of unsorted work — the "nothing is finished" impression you most want to avoid. **Proposal:** put one `## [0.1.0] — 2026-xx-xx` heading above the existing content and move the essays to a `## Development log` below it or to a separate file, leaving roughly 40 one-line entries under 0.1.0. Nothing needs to be thrown away; it just needs to stop being the first 4,900 lines. Write the new 0.1.0 heading and its summary in English, so the first screen matches the language of the README.

brenno added the

docs

label

2026-07-22 16:19:53 +00:00

brenno referenced this issue from a commit

2026-07-22 17:07:10 +00:00

docs(changelog): geef 0.1.0 een kop, en haal het dode adres eruit (#609 #645)

brenno referenced this issue from a commit

2026-07-22 17:12:52 +00:00

docs(changelog): geef 0.1.0 een kop, en haal het dode adres eruit (#609 #645)

brenno referenced this issue

2026-07-22 17:14:10 +00:00