Changelog Workflow

Shared source of truth for generating or updating CHANGELOG.md from git history before a release.

Update CHANGELOG.md with a new entry based on git history since the last documented release. Use Keep a Changelog format.

Arguments

  • Optional version string (e.g. 0.7.0)

  • If omitted, read the current version from pyproject.toml and use that

1. Gather context

Run these commands to understand what changed:

# Find the last version documented in CHANGELOG.md
# (first line matching "## [<version>]" or "## <version>")
head -100 CHANGELOG.md

# Get current version from pyproject.toml
grep '^version' pyproject.toml

# Find the most recent git tag
git tag --sort=-v:refname | head -5

# Get all commits since the last tag (or since the last documented version)
git log <last_tag>..HEAD --oneline --no-merges

# For richer context, also read the full commit messages
git log <last_tag>..HEAD --no-merges --format="%h %s%n%b"

2. Categorize changes

Read the commits and diffs to understand what actually changed. Group changes into these categories and omit empty categories:

  • Added -> new features, new functions, new API methods

  • Changed -> behavior changes, API changes, renamed things

  • Fixed -> bug fixes

  • Removed -> removed features or deprecated code

3. Write the entry

Write human-readable changelog entries. Rules:

  • Write for users, not developers. “Added pGauss profile function for Gaussian depth profiles” not “added pGauss to profile.py”.

  • Group related commits into single entries. Five commits that refine one feature = one changelog bullet.

  • Skip internal-only changes like CI tweaks, test refactors, code style fixes, or pre-commit config changes unless they affect the user (e.g. “Tests now run on Python 3.14”).

  • Mention breaking changes prominently. If an API was renamed or removed, say what the old name was and what to use instead.

  • Use backticks for code identifiers (function names, parameter names, etc).

  • Each bullet should be one concise sentence, two at most.

4. Update CHANGELOG.md

  • Read CHANGELOG.md to match the existing style and header. The file uses Keep a Changelog format and Semantic Versioning.

  • Insert the new version entry after the header and before any existing entries. If there’s an [Unreleased] section, replace it.

  • Format:

## [<version>] - <YYYY-MM-DD>

### Added
- ...

### Changed
- ...

  • Use today’s date for the release date.

5. Show the result

Print the new entry so the user can review it before committing.