Release notes and CHANGELOG

Every archived change already says why it was made and what changed. codev turns that into release notes: each proposal carries a short ## Release note for end users, and codev changelog assembles the notes of the changes archived since the last release. Choosing the version, tagging and publishing stay with you and your release tooling.

Write the release note with the proposal

/codev-propose writes the section with the rest of the proposal, after ## Impact:

## Release note

- Added: `--format json` on `codev export`.
- Changed: **BREAKING** `codev export` writes to stdout by default; pass
  `--output <PATH>` to write a file.

Each item is - <Category>: <text>, with one of the six categories of Keep a Changelog: Added, Changed, Deprecated, Removed, Fixed, Security. The categories stay in English; the text follows the artifact language. Write for the people who use the product, not for the people who build it. A breaking item starts with **BREAKING**. A change nobody will notice — a refactoring, a test, a CI tweak — writes the single line None.

codev validate checks the section on active changes: a missing section is a warning (release_note_missing), an unknown category, an item without text or an empty section is an error (release_note_invalid). The full format is in File formats.

Generate the notes

codev changelog

## [Unreleased]

### Added

- `--format json` on `codev export`.

### Changed

- **BREAKING** `codev export` writes to stdout by default; pass `--output <PATH>` to write a file.

The range is decided by git: the changes whose folder is in _codev/changes/archive/ now and was not at the latest v* tag. Use --since <ref> and --until <ref> for another range — for instance the notes of a past release:

codev changelog --until v1.4.0 --format markdown

--until v1.4.0 starts after the version tag just below it, v1.3.x. --format markdown drops the version heading, which suits a release body; --format json gives the entries to scripts (see JSON output).

Changes archived before release notes existed have no ## Release note: their What Changes bullets are listed under Changed, and a release_note_missing warning names each of them so you can review the wording. A change whose specs remove requirements without a Removed or BREAKING item gets a release_note_inconsistent warning.

Keep CHANGELOG.md up to date

codev changelog --write

--write puts the [Unreleased] block into CHANGELOG.md, between codev’s markers, right after the file header — the file is created with a standard header if it does not exist:

# Changelog

All notable changes to this project are documented in this file.

<!-- codev:begin — generated by `codev changelog --write` from the archived changes; edit outside this block -->
## [Unreleased]

### Added

- `--format json` on `codev export`.
<!-- codev:end -->

## [1.3.0] - 2026-09-30
…

Released versions, hand-written text and the links at the bottom of the file stay as they are. Running the command again with nothing new leaves the file unchanged. codev doctor reports a changelog warning when the section is behind the archive, or when CHANGELOG.md is missing.

Note If CHANGELOG.md already has a hand-written ## [Unreleased] heading, the first --write takes it over: the managed section replaces that heading, and the entries you wrote below it stay where they are, under the same section.

Release

Right before tagging:

codev changelog --release 1.4.0 --write

The generated block becomes ## [1.4.0] - <today> (or --date YYYY-MM-DD), outside the markers, and a new empty ## [Unreleased] takes its place in the managed section. Commit, then tag v1.4.0 right away: until the tag exists, codev changelog still counts those changes as unreleased.

On GitHub, the release workflow can use the same notes for the release body, built with the codev of the tagged commit:

codev changelog --until "$GITHUB_REF_NAME" --format markdown > release-notes.md

Adopting it in an existing project

If your CHANGELOG.md already describes changes that were archived without a release note, list them under changelog.exclude in _codev/config.yaml, so they are not listed a second time:

changelog:
  exclude:
    - 2026-09-30-legacy-import

Once the next version is tagged, they are out of range and the list can be emptied. See Configuration.