mkchangelog

CI/CD
Package
Meta

Use this CLI tool to create a changelog for a project from the git log using the conventional commits scheme.

NOTE: Since version 2.0.0 there are some significant changes:

• mkchangelog generate writes to --output file as default - use --stdout to write to stdout
• mkchangelog config commands was renamed to mkchangelog settings
• options in .mkchangelog along with mkchangelog generate options were changed to be more consistent, use mkchangelog settings --generate to get new config file
• the mkchangelog generate options --renderer and --template were merged as --template [renderer name | path to template]

For other parameters changes refer to usage section.

Features:

Changelog generation:

• generate full CHANGELOG.[md,rst,txt,json] mkchangelog generate --renderer <markdown | rst | txt | json>
• limit included commit types mkchangelog generate --types feat,fix,refactor
• group commits by type and by scope also
• include unreleased changes section (mkchangelog generate --include-unreleased)
• pass own template by --renderer template --template ./path/to/template.jinja - check internal templates

Configuration generation:

• configure mkchangelog using .mkchangelog INI file (mkchangelog config --generate > .mkchangelog)

Commit message helper:

• create mkchangelog.txt with proper commit message mkchangelog commit [--stdout], then git commit -F message.txt

Bump version:

• compute and bump next version (using semver) mkchangelog bump

Table of Contents

• Installation
• Usage
• License

Installation

pip install mkchangelog
pip install mkchangelog[colors]  # for console colorized output

Usage

The list of versions is taken from list of signed git tags detected by prefix (default v, f.e. v1.3.4).

To generate changelog for current and all previous versions (signed tags) to CHAGELOG.md (default):

mkchangelog generate [--stdout] [--template <markdown | rst | json | ./tmpl.jinja >]

❯ mkchangelog generate --help
usage: mkchangelog generate [-h] [-o OUTPUT] [-t TEMPLATE] [-l COMMIT_LIMIT] [-u] [-uv UNRELEASED_VERSION] [--hide-empty-releases]
                            [--changelog-title CHANGELOG_TITLE] [--tag-prefix TAG_PREFIX] [--commit-types COMMIT_TYPES_LIST [COMMIT_TYPES_LIST ...]]
                            [--stdout]

options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        output file, default: CHANGELOG.md
  -t TEMPLATE, --template TEMPLATE
                        specify template to use [markdown, rst, json], or path to your template default: markdown
  -l COMMIT_LIMIT, --commit-limit COMMIT_LIMIT
                        number of commits to display per release, default: 100
  -u, --unreleased      include unreleased changes in changelog
  -uv UNRELEASED_VERSION, --unreleased-version UNRELEASED_VERSION
                        use specified version as unreleased release; default 'Unreleased'
  --hide-empty-releases
                        skip empty versions
  --changelog-title CHANGELOG_TITLE
                        changelog title, default 'Changelog'
  --tag-prefix TAG_PREFIX
                        version tag prefix; default 'v'
  --commit-types COMMIT_TYPES_LIST [COMMIT_TYPES_LIST ...]
                        f.e. feat,fix,refactor, all - for all convigured; default from 'commit_types_list' settings
  --stdout              output changelog to stdout

To generate commit message use:

$ mkchangelog commit --stdout
Git Commit Format: type(scope): summary

Commit Type [build,chore,ci,dev,docs,FEAT,fix,perf,refactor,style,test,translations]: feat
Scope: (optional): commands
Summary line: add `mkchangelog commit` command to generate proper commit message
Is breaking change? [y/N]
Long description (body): The message be displayed at stdout by passing `--stdout` parameter. Otherwise will be saved as `message.txt` file.
---
feat(commands): add `mkchangelog commit` command to generate proper commit message

The message be displayed at stdout by passing `--stdout` parameter. Otherwise will be saved as `message.txt` file.
---

Experimental commands:

Interactive tool to generate changelog, bump version, commit changelog and tag version:

mkchangelog bump ## The 'bump' commands gets same parameters as 'generate'

Configuration

You can change default configuration using .mkchangelog (ini format) file in current directory.

mkchangelog settings --generate  # generates default .mkchangelog file

mkchangelog settings # shows current default settings merged with .mkchangelog settings

Default configuration is:

[GENERAL]
output = CHANGELOG.md
template = markdown
commit_limit = 100
unreleased = False
unreleased_version = Unreleased
hide_empty_releases = False
changelog_title = Changelog
commit_types_list = fix,feat
commit_type_default_priority = 10
tag_prefix = v

[commit_types]
build = Build
chore = Chore
ci = CI
dev = Dev
docs = Docs
feat = Features
fix = Fixes
perf = Performance
refactor = Refactors
style = Style
test = Test
translations = Translations

[commit_types_priorities]
feat = 40
fix = 30
refactor = 20

Contributing

Install pre-commit

pip install pre-commit
pre-commit install

Run tests

hatch run all:test

Linting

hatch run lint:all

License

mkchangelog is distributed under the terms of the MIT license.