docs: write down the changelog convention, and apply it to 20.2.0 - #1613
Merged
Conversation
The 20.2.0 section had drifted a long way from how this changelog is written.
Measured against the rest of the file, its entries averaged 890 characters
where 18.3.0 runs about 250, and it opened straight into a bullet list with no
`**Highlights:**` paragraph.
Worse than the length, five of its eleven `Fixed` entries did not belong there
at all:
- two duplicated their own `Performance` entries, describing the same change
twice
- three documented bugs that never reached a release — one said outright
that no released version was affected, another was latent until a
same-cycle change exposed it, and the third was about the test suite
A user reading those learns nothing; they record how the work went, not what
changed for them.
CONTRIBUTING.md now states the convention: `Subsystem: what changed` in one or
two sentences, the mechanism and the symptom without the discovery narrative,
nothing that only ever existed inside an unreleased cycle, `Changed` reserved
for user-facing API changes, and measurements quoted no more precisely than
they were taken.
20.2.0 is rewritten to match: 11 entries averaging 393 characters, a Highlights
opener, and issue references in the bare `(#1234)` form the older sections use.
Released sections are left alone. They are published — each has a GitHub
release carrying a copy — so editing them here would only make the two
diverge.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Aa37KGXZcnVrbn1yG4j1N
Entries across the 19.3 to 20.1 range had drifted well past the house style,
peaking at 20.1.0's three entries averaging 1166 characters. Trimmed to the
one or two sentences CONTRIBUTING now describes, keeping the mechanism and the
symptom and dropping the discovery narrative.
version entries before after
20.1.1 7 538 277
20.1.0 3 1166 458
20.0.0 51 423 352
19.8.0 26 525 354
19.7.1 3 539 244
19.7.0 39 525 274
19.5.0 51 636 382
19.4.0 12 511 268
19.3.0 21 647 305
19.4.0, 20.1.0 and 20.1.1 were rewritten by hand, since they also needed
restructuring into `Subsystem: what changed`. The rest already had that shape
and only needed shortening.
No entry was removed and no fact dropped beyond the narrative — these are
published notes, so the record stays intact. Verified afterwards: nothing cut
mid-clause, and one entry that split at "(e.g." was repaired by hand.
Note the published GitHub releases still carry the original text, so the two
now differ.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Aa37KGXZcnVrbn1yG4j1N
…eference space The feature list named seven blend modes. There are thirteen, and as of 20.2 every one of them works identically on WebGPU, WebGL 2 and Canvas — `exclusion` landed in 20.0 and the six shader-path modes in 20.2. Understating that in the README hides the release's headline. Also mentions the particle reference space, since "blend modes" was the only particle capability called out and this is the larger addition. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Aa37KGXZcnVrbn1yG4j1N
DOC_README.md is what `pnpm doc` passes to typedoc as `--readme`, so it is the
landing page a new user reads first. It had gone unmaintained across eight
releases:
- the Quick Start had no `await app.init()`, mandatory since 20.0, so the
very first snippet anyone copied could not run
- the feature table said "WebGL & Canvas 2D" through the whole of 20.x,
omitting the backend that release was built around
- the shader sample taught `renderable.shader =`, deprecated since 19.2.0 in
favour of `addPostEffect()`
The cause is structural: two READMEs with overlapping content in different
directories. The root one is updated every release; this one, tucked inside
packages/melonjs, was invisible. It now sits beside the README it duplicates.
Placement alone does not enforce anything, so `scripts/check-doc-readme.ts`
runs before typedoc and fails the build when a sample constructs an
`Application` without awaiting `init()`, when a sample uses a member marked
`@deprecated` anywhere in src, or when the page stops naming a renderer the
engine supports. Deprecated members are scanned from the source rather than
listed, so something deprecated later is covered without anyone remembering
this file. Both original bugs were verified to fail it.
Also fixes the ParticleEmitter class doc, which rendered as a broken category
name in the sidebar — "Particles ### Blend modes An emitter draws no pixels of
its own..." — because `@category` is a block tag and the sections added in
#1604 and #1606 sat after it, so they were absorbed into its value. Prose now
comes first with `@category` last, and the two `@example` tags are fenced code
blocks, which cannot swallow what follows. Verified in the built output: both
sections render as h3 headings and no raw markdown leaks.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Aa37KGXZcnVrbn1yG4j1N
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Aa37KGXZcnVrbn1yG4j1N
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The 20.2.0 section had drifted a long way from how this changelog is written.
The bigger problem was what was in it
Five of eleven
Fixedentries did not belong in a user changelog:Performanceentries — the lazy bounds and the WebGPU memo were each described twice, because the Performance entries were added without removing the originals.CanvasRenderTarget.invalidate()entry said outright "no released version is affected". The batcher-bind one was "latent until then" — it existed only because of a same-cycle change. The third was about our test harness.Those record how the work went, not what changed for anyone using the engine.
CONTRIBUTING.md
Now states the convention, so this stops drifting:
Subsystem: what changed, in one or two sentencesChangedis for user-facing API changes only; a game looking different because of something underAddedis not a change**Highlights:**(thanks @user)Released sections untouched
They are published — each has a GitHub release carrying a copy — so editing the file would only make the two diverge. The drift starts around 19.3.0 and is worth knowing about, but retroactive edits are churn without benefit.
🤖 Generated with Claude Code
https://claude.ai/code/session_012Aa37KGXZcnVrbn1yG4j1N