Orkuncakilkaya
5c4c10a1d7
build_section piped every changeset body through `tr '\n' ' '`. A multi-line changeset came out as one paragraph, so nested bullets rendered as inline " - " runs and a whole release read as a single unbroken block — v0.3.0 was one ~4 KB bullet. The renderer is now Ludic rather than a shell one-liner. A section is grouped by conventional-commit type (Features, Fixes, Performance, ...), each changeset is one bullet, and continuation lines are indented two spaces so nested lists and paragraphs stay inside their item. Bullets are sorted within a group, so cutting the same release twice produces the same text. Also: - `x release --dry-run` renders the pending section to stdout and touches nothing, so a release can be read before it is cut. - `x changelog-render` re-renders a section from a directory of changesets, and `x changelog-section` prints one release's section back out of CHANGELOG.md. - The v0.1.0 and v0.3.0 sections are re-rendered with the former, from the changesets recovered at each tag's parent commit; the bullet counts (6 and 25) and word multisets are unchanged. v0.2.0 is left alone: it carries a hand-written summary and topical subheadings, and regenerating it would have replaced curation with raw changeset dumps. The file header now says that a section may carry such a summary, since it previously claimed released sections are never hand-edited. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
51 lines
1.7 KiB
Markdown
51 lines
1.7 KiB
Markdown
# Changesets
|
|
|
|
A **changeset** is one small Markdown file describing a single user-facing change,
|
|
dropped in this directory. `x release` consumes every changeset here into a new
|
|
`CHANGELOG.md` section, bumps `VERSION`, and deletes the consumed files.
|
|
|
|
## Format
|
|
|
|
```
|
|
bump: minor
|
|
type: feat
|
|
One or more lines describing the change, in the past-agnostic imperative used in
|
|
the changelog. Markdown is fine.
|
|
```
|
|
|
|
- `bump:` — `major`, `minor`, or `patch` (SemVer). The release version is bumped
|
|
by the **highest** level among the pending changesets (unless `x release <level>`
|
|
overrides it).
|
|
- `type:` — the Conventional Commit type (`feat`, `fix`, `perf`, `docs`, …). It
|
|
decides which group the change lands in: `feat` → **Features**, `fix` →
|
|
**Fixes**, `perf` → **Performance**, and so on, in that order. A type with no
|
|
known heading gets one named after itself.
|
|
|
|
## Writing the body
|
|
|
|
The body is markdown and reaches the changelog as markdown: it becomes one list
|
|
item, with continuation lines indented to stay inside it. Nested bullets, blank
|
|
lines between paragraphs and inline code all survive.
|
|
|
|
```
|
|
bump: minor
|
|
type: feat
|
|
**Tiled map support** — load and draw Tiled maps.
|
|
|
|
- **TMX/TSX** — the XML formats, decoded to the same intermediate as JSON.
|
|
- **Collision** — the `collision` layer projects onto the engine tilemap.
|
|
```
|
|
|
|
Lead with the thing that changed, not with the mechanism. A reader scanning the
|
|
release should be able to stop after your first clause.
|
|
|
|
## Adding one
|
|
|
|
Create a file with a short, unique name, e.g. `changes/regex-namespace.md`. Any
|
|
filename works except this `README.md`, which the release step always skips.
|
|
|
|
Preview how the next release will read before cutting it — this writes nothing:
|
|
|
|
```bash
|
|
x release --dry-run
|
|
```
|