Skip to content

Quick start

This page walks you from zero to a working changelog in a few minutes.

1. Install

uv tool install keepachangelog-manager-fork

2. Create a changelog

In your project root:

changelogmanager create

This writes a minimal CHANGELOG.md:

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

If you want config first, run:

changelogmanager config init

That interactive setup defaults to pyproject.toml and semver, then asks whether to enforce the preamble plus the default component name and changelog path. If you pick pep440 or calver, future create runs use that wording in the generated preamble.

Already have tagged releases?

If you are adopting the tool in an existing repository, you can backfill missing released sections from local git history before adding new unreleased entries:

changelogmanager backfill --source all --dry-run
changelogmanager backfill --source all

Backfill uses local tags and can classify commit subjects between tag intervals using Conventional Commits, gitmoji, or Keep a Changelog-flavored prefixes. If no richer commit entries are available, each missing version gets a conservative placeholder under Changed, for example: Release notes unavailable; backfilled from tag \v1.2.3`.Existing versions already present inCHANGELOG.md` are left alone.

3. Add a change

changelogmanager add --change-type added --message "Initial release"

Your changelog now contains:

## [Unreleased]
### Added
- Initial release

4. Release

changelogmanager release

The [Unreleased] section is renamed to the inferred next version with today's date:

## [0.0.1] - 2024-05-01
### Added
- Initial release

If your pyproject.toml also contains a version = "..." line, that string must match the released version before you build and publish. Use --bump-versions to update it in the same step:

sh changelogmanager release --bump-versions --yes

Without this, the changelog and pyproject.toml (and any __version__ in your source) will drift, and your package will be published under the wrong version number. See Syncing version strings for the full details and the [jiggle] extra required to enable this flag.

5. Validate at any time

changelogmanager validate

No output means no errors. Errors are printed in LLVM diagnostic format by default (compatible with many editors and CI systems).

If you want the tool to clean up common issues for you, use:

changelogmanager validate --fix

This can reorder released versions, lowercase change-type headings, drop empty sections, and remove duplicate entries.

6. Edit or remove an unreleased entry

List entries with their indices:

changelogmanager remove --list

Update an existing entry:

changelogmanager edit --change-type added --index 0 --message "Initial public release"

Remove an entry:

changelogmanager remove --change-type added --index 0

7. Prefer commit history over typing?

Seed [Unreleased] from git commit subjects:

changelogmanager from-commits

By default this starts at the last git tag, falling back to full history when no tag exists. Use --strict to skip subjects that do not match the selected commit schema instead of treating them as changed.

Prefer a GUI?

If you'd rather click than type, run:

changelogmanager gui

This opens a multi-screen Tkinter app for editing [Unreleased], backfilling from history, publishing releases, and running batch component operations. See the Desktop GUI page for details.

What's next

  • Learn the full set of workflows including backfill, GitHub/GitLab releases, commit seeding, exports, and automation flags
  • Read the complete CLI reference for every flag and option
  • Try the Desktop GUI for an interactive front-end