Mark each kind of change in the changelog, and hold the convention with a test #80

New issue

Closed

opened 2026-09-07 10:59:38 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-09-07 10:59:38 +00:00

Owner

Observation

also on the change logs, i like the new tendency of replacing for example bugs by the
emoji worm, etc

What exists today

CHANGELOG.md follows Keep a Changelog with plain
headings — ### Added, ### Changed, ### Fixed. The entries under them are long, because
each says why rather than what, which is the house style and worth keeping. The cost is
that scanning the file for "what broke and got fixed" means reading headings that all look
alike.

Shape

An emoji before each Keep a Changelog heading, and the word kept beside it. The word is what
makes it readable in a plain-text terminal, in a screen reader, and to anybody whose font
does not have the glyph; the emoji is what makes it findable at a glance.

Heading
`### ✨ Added`	a new capability
`### 🔧 Changed`	behaviour that already existed, now different
`### 🐛 Fixed`	a defect
`### 🔒 Security`	anything with a security consequence
`### ⚠️ Deprecated`	on the way out
`### 🗑️ Removed`	gone

Applied to every section in the file, not only the new ones: a convention half-applied reads
as a mistake rather than a convention.

Enforced, like the project's other conventions. tests/test_template_lint.py refuses a
template that names a side of the page; tests/test_fonts.py holds the image's fonts to the
languages offered. A heading in CHANGELOG.md that is not one of the six above, or is one of
them without its mark, should fail the same way — otherwise this decays into some sections
having emoji and some not, which is worse than none having them.

What has to keep working

scripts/release_tools.py builds a release's notes from the changelog. It matches on
## [version] and takes everything up to the next ## , so the ### subheadings inside are
carried through untouched — the emoji land in the release notes, which is where they are
wanted. Checked before changing anything: no parser reads the subheadings.

Classification

Documentation.

## Observation > also on the change logs, i like the new tendency of replacing for example bugs by the > emoji worm, etc ## What exists today `CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) with plain headings — `### Added`, `### Changed`, `### Fixed`. The entries under them are long, because each says *why* rather than *what*, which is the house style and worth keeping. The cost is that scanning the file for "what broke and got fixed" means reading headings that all look alike. ## Shape An emoji before each Keep a Changelog heading, and the word kept beside it. The word is what makes it readable in a plain-text terminal, in a screen reader, and to anybody whose font does not have the glyph; the emoji is what makes it findable at a glance. | Heading | | | --- | --- | | `### ✨ Added` | a new capability | | `### 🔧 Changed` | behaviour that already existed, now different | | `### 🐛 Fixed` | a defect | | `### 🔒 Security` | anything with a security consequence | | `### ⚠️ Deprecated` | on the way out | | `### 🗑️ Removed` | gone | Applied to every section in the file, not only the new ones: a convention half-applied reads as a mistake rather than a convention. **Enforced, like the project's other conventions.** `tests/test_template_lint.py` refuses a template that names a side of the page; `tests/test_fonts.py` holds the image's fonts to the languages offered. A heading in `CHANGELOG.md` that is not one of the six above, or is one of them without its mark, should fail the same way — otherwise this decays into some sections having emoji and some not, which is worse than none having them. ## What has to keep working `scripts/release_tools.py` builds a release's notes from the changelog. It matches on `## [version]` and takes everything up to the next `## `, so the `###` subheadings inside are carried through untouched — the emoji land in the release notes, which is where they are wanted. Checked before changing anything: no parser reads the subheadings. ## Classification Documentation.

tiagoagueda added this to the 0.3.0 milestone

2026-09-07 10:59:38 +00:00

tiagoagueda added the

documentation

tier

labels

2026-09-07 10:59:38 +00:00

tiagoagueda referenced this issue from a commit

2026-09-07 11:02:45 +00:00

Mark each kind of change, and hold the convention with a test

tiagoagueda closed this issue

2026-09-07 11:02:45 +00:00