changesets

This repository releases through changesets. Writing one is part of finishing the work, not a step somebody has to ask for.

What gets one

A changeset describes what changed against main, not what changed against the last commit.

A branch often introduces something and then corrects it a few commits later. Nobody reading CHANGELOG.md ever saw the broken version, so that correction gets no changeset of its own. Amend the feature's own changeset instead, if it now claims something untrue.

The test is one question: did the behaviour being fixed ever reach main? A fix for something players have today, or anything main does not have at all, gets a changeset as usual.

The bump level

The question is not how big the change looks or how visible it is on screen. It is whether the thing existed before.

patch. Something that already existed now behaves differently. A bug fixed, a number retuned, a rendering path rewritten, a screen relaid, a performance win. All of these are patch however different the result looks. A rendering change that alters what a player sees is still a fix.

minor. Something exists now that did not exist before. A new weather, a new item, a new ability, a new NPC, a new screen, a new field on a record that callers can set. If a player or a developer could not have reached it yesterday and can today, it is minor.

major. Ask first. Never write one on your own judgement. Say what you think warrants it and let the maintainer decide.

The two questions are worth keeping separate, because a single change often does both. Adding a fourth rarest sky is minor; retuning the threshold that decides how often the existing three appear is patch. When one changeset covers both, take the higher of the two.

The file

A markdown file in .changeset/, named in kebab-case as a short sentence about the change rather than as a ticket or a component: held-rather-than-hovered.md, nests-wait-for-babies.md, four-corners-of-the-sky.md.

---
'overwander': minor
---

One line saying what is true now.

The package is always overwander.

The prose

Keep it short. One line for one change. A changeset is a changelog entry, not a summary of the work: it says what is true now and stops. Resist explaining the reasoning, the trade-offs or what it replaced.

Where a change covers several things, use a list rather than paragraphs, one line each:

---
'overwander': patch
---

- Evolution rows on a shiny catch sheet no longer show the ordinary coat.
- A gifted species nobody has met draws a silhouette instead of Missingno.

Write for someone reading CHANGELOG.md, not someone reading the diff. Name the behaviour, not the file or the function.

The repository's usual prose rules apply: no em-dashes, plain sentences, no build-up. Wrap around 80 columns like the files already there.

Where a change touches world generation, say so on its own line, because it changes what every existing player sees.

Before concluding one is missing

The release step folds every changeset into CHANGELOG.md and empties .changeset/, so a directory holding only README.md and config.json does not mean the work went unrecorded. Check CHANGELOG.md before writing a second one for something already shipped.