NAME

repomatic lint-changelog - Check changelog dates against release dates

SYNOPSIS

repomatic lint-changelog [OPTIONS]

DESCRIPTION

Verify that changelog release dates match canonical release dates.

Uses PyPI upload dates as the canonical reference when the project is published to PyPI. Falls back to git tag dates for non-PyPI projects.

PyPI timestamps are immutable and reflect the actual publication date, making them more reliable than git tags which can be recreated.

Also detects orphaned versions: versions that exist as git tags, GitHub releases, or PyPI packages but have no corresponding changelog entry. Orphans cause a non-zero exit code.

Reads pypi-package-history from [tool.repomatic] to fetch releases published under former package names (for renamed projects).

Reads abandoned-versions from [tool.repomatic] to skip "not found on PyPI" warnings for releases that were frozen but never published (skip-and-move-forward releases).

Reads changelog.bullet-word-threshold from [tool.repomatic] to warn, non-fatally, about unreleased changelog bullets longer than that many words. A changelog entry is a release note, not a commit message.

Warns, non-fatally, about a released section holding no entry: a published release heading with nothing under it reads as broken to anyone scanning the notes for that version.

Output symbols:


    ✓  Dates match


    ⚠  Version not found on reference source (warning, non-fatal)


    ✗  Date mismatch (error, fatal)

With --fix, the command also:


    - Corrects mismatched dates to match the canonical source.


    - Adds a PyPI link admonition under each released version.


    - Adds a CAUTION admonition for yanked releases.


    - Adds a WARNING admonition for versions not on PyPI.


    - Inserts placeholder sections for orphaned versions.

Exit codes:


    0  All dates match, or --fix corrected the file.


    1  Date mismatch or orphan detected without --fix.


    2  Sanity gate refused to rewrite: upstream lookup (PyPI or


       GitHub Releases) looks unhealthy and the existing changelog


       has substantial coverage that would be silently stripped.


       Re-run when the API is reachable.

OPTIONS

--changelog FILE

Path to the changelog file. Defaults to the configured changelog.location.

--package TEXT

PyPI package name for date lookups. Auto-detected from pyproject.toml.

--fix

Fix date mismatches and add PyPI admonitions to the changelog.

--help / -h

Show this message and exit.

ENVIRONMENT

LINT_CHANGELOG_CHANGELOG_PATH

Path to the changelog file. Defaults to the configured changelog.location.

LINT_CHANGELOG_PACKAGE

PyPI package name for date lookups. Auto-detected from pyproject.toml.

LINT_CHANGELOG_FIX

Fix date mismatches and add PyPI admonitions to the changelog.

LINT_CHANGELOG__CLICK_DEFAULT_HELP

Show this message and exit.

EXIT STATUS

0

Success.

1

A runtime error, or an aborted prompt (Ctrl-C, a declined confirmation).

2

A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.

EXAMPLES

Check the default changelog.md (auto-detects PyPI package)

repomatic lint\-changelog

Fix dates and add admonitions

repomatic lint\-changelog \-\-fix

Explicit package name

repomatic lint\-changelog \-\-package repomatic

AUTHORS

Kevin Deldycke