RELEASE_NOTES

Release notes

What the updater shows the user as "what's new," and where it comes from.

Four sources are tried in order; the first one that produces anything wins:

Source	Where it reads from
notices	A per-version YAML file in a notices/ folder in the repo
changelog	The section of CHANGELOG.md matching the new version
release	The release body as published on the git host
none	Skip notes entirely

Set with notes.source: auto | notices | changelog | release | none. auto (the default) tries notices, then changelog, then the release body, so a project gets good notes for free if it already keeps them in the repo, and still gets something if it doesn't.

Notes are never worth failing an update over - if a source can't be read, the updater logs it at debug level and falls through to the next one rather than erroring.

The notices format

The richest option, because it's written for end users rather than for git log:

id: "v1.2.3"
title: "MyApp 1.2.3"
message: |
  ### New
  - Feature X

  ### Fixed
  - Bug Y

One file per version in notices/. Both the active notices/ folder and a notices/history/ subfolder are searched, since a file tends to move from one to the other as versions age out.

Configure the folder name with notes.notices_dir (default notices).

Changelog fallback

Matches a markdown heading like ## [1.2.3] - 2026-08-01 or ## v1.2.3 against the new version and takes that section. Checked at notes.changelog_paths (default [CHANGELOG.md, docs/CHANGELOG.md]).

Release body fallback

Whatever the git host's release page shows - the description entered when the release was published. Works with every backend, so it's the fallback of last resort.

Limits

notes.max_length (default 20000 characters) truncates a long body at a line boundary rather than mid-sentence, appending ....

See also

• BACKENDS - fetch_text_file() / list_directory() are what let a backend support the notices and changelog sources; a backend that can't implement them just returns nothing and auto falls through
• README - configuration file