Skip to main content

Generate changelog from git log with convencional commits.

Project description

mkchangelog

CI/CD CI - Test
Package PyPI - Version PyPI - Downloads PyPI - Python Version
Meta linting - Ruff code style - Black types - Mypy License - MIT

The CHANGELOG.md generator from git log using the conventional commits scheme.

Example generated changelog: CHANGELOG.md

Table of Contents

Installation

pip install mkchangelog

Usage

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

Generate changelog

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

$ mkchangelog generate       # Creates CHANGELOG.md
$ mkchangelog g              # Creates CHANGELOG.md
$ mkchangelog g --stdout     # Prints changelog to stdout
$ mkchangelog g --help       # Prints help for generate command
$ git mkc g                  # git mkc alias for mkchangelog

Generate commit message

$ mkchangelog commit         # Generates message.txt
$ mkchangelog c              # Generates message.txt
$ git mkc c                  # git mkc alias for mkchangelog
$ git commit -F message.txt  # Use message.txt as commit message

Bump version

Interactive tool to:

  • generate changelog
  • calculate next version from feat/fix/breaking changes commits
  • commit changelog and tag version
$ mkchangelog bump           # Bumps next version
$ mkchangelog b              # Bumps next version
$ mkchangelog b --show-current-version  # Only show current version
$ mkchangelog b --show-next-version     # Only show next version
$ git mkc b                  # git mkc alias for mkchangelog

Manage configuration

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

$ mkchangelog settings       # Shows current config as jon
$ mkchangelog s              # Shows current config as jon
$ mkchangelog s --generate   # Prints default config ini file
$ git mkc s                  # git mkc alias for mkchangelog

Configuration

Default configuration is:

[GENERAL]
output = CHANGELOG.md                   ; output file
template = markdown                     ; template to use
commit_limit = 100                      ; commits limit per release (version)
unreleased = False                      ; include unreleased changes (HEAD...last_version)
unreleased_version = Unreleased         ; title of unreleased changes (f.e. next version v3.0.0)
hide_empty_releases = False             ; hide releases with no gathered commits
changelog_title = Changelog             ; Changelog title
commit_types_list = fix,feat            ; list of commit types to include in Changelog
commit_type_default_priority = 10       ; default priority of commit type, for Changelog ordering
tag_prefix = v                          ; versions tag prefix to detect/generate git tags
ignore_revs = 3a3bc...,...              ; ignore certain git revisions durint generating Changelog

[commit_types]                          ; valid commit types (for `--commit-types all`) and their names
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]               ; custom commit types priorities, for Changelog ordering
feat = 40
fix = 30
refactor = 20

Features

Creates changelog from git log

  • the list of releases is created from list of annotated git tags matching configured tag_prefix.
  • the unreleased changes are included if unreleased is true.
  • from git log messages matching configured commit_types are parsed and grouped by the type.
  • certain groups (types) are sorted by configured commit_types_priorities.
  • only configured commit_types_list types are rendered, if not --commit-types [type,type, | all] was provided
  • you can also set ignored_revs list in .mkchangelog, to skip certain git revisions by sha

Includes additional git commits from text files

  • additional commit files (*.txt) can be put at .mkchangelog.d/versions/<version>/commits/ directory

For example:

Built-in templates

The mkchangelog includes a few builtin changelog output formats

$ mkchangelog g --template markdown
$ mkchangelog g --template rst
$ mkchangelog g --template json

Custom header and footer per version [for built-in templates]

The header and footer files are included from files:

  • .mkchangelog.d/versions//header
  • .mkchangelog.d/versions//footer

For example:

Custom jinja templates

You can create your own templates and pass them by --template parameter of mkchangelog generate or set it in .mkchangelog configuration file.

Using configuration file

[GENERAL]
...
# put `custom_template.jinja` in `.mkchangelog.d/templates/
template = custom_template.jinja

# or specify full path to template
template = ./path/to/template.jinja
...

Using --template parameter*

# put `custom_template.jinja` in `.mkchangelog.d/templates/
$ mkchangelog g --template custom_template.jinja

# or specify full path to template
$ mkchangelog g --template ./path/to/template.jinja

Refer to built-in templates for examples:

Template filters

Apart from builtin jinja2 filter there are additional custom filters:

  • underline - f.e. {{ changelog.title | underline('=') }}
  • regex_replace - f.e. {{ "line with #12 issue ref" | regex_replace("#(\d+)", "#ISSUE-\\1") }}

You can create and register your own filters using .mkchangelog.d/hooks.py file.

Example implementation of hooks:

Your own commit types

The commit_types can be fully customized by .mkchangelog file.

[GENERAL]
commit_types_list = awesome
hide_empty_releases = True

[commit_types]
awesome = Best change
sad = Had to write it
not_sure = Works but why?

[commit_types_priorities]
awesome = 40
sad = 30
not_sure = 20
$ mkchangelog g --commit_types all
$ mdless CHANGELOG.md

image

Plugins / hooks system

You can use hooks system to extend mkchangelog functionality. All hooks are loaded from .mkchangelog.d/hooks.py file which must be a valid python module.

You can check the specification for available hooks at hookspecs.py file. The mkchangelog built-in hooks are implemented at lib.py file.

Available hooks:

  • provide_template_filters - returns dictionary of jinja2 filters,
  • provide_changelog_loglines_filter - returns functions which filters list of LogLine - you can use it to filter out f.e. some scopes

Example .mkchangelog.d/hooks.py

from __future__ import annotations

import random
from typing import Any, Callable, Dict, List

from mkchangelog.config import Settings
from mkchangelog.lib import hookimpl


def fancylize(s):
    return "".join([c.lower() if random.randint(0, 1) else c.upper() for c in s])


@hookimpl
def provide_template_filters(settings: Settings) -> Dict[str, Callable[[Any], str]]:  # noqa
    """Add 'fancylize' jinja2 template filter"""
    return {"fancylize": fancylize}


@hookimpl
def provide_changelog_loglines_filter(settings: Settings) -> Callable[[List[LogLine]], List[LogLine]]:
    """Hide lines with scope 'hidden_scope'"""
    return lambda loglines: [line for line in loglines if line.scope != "hidden_scope"]

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkchangelog-2.6.0.tar.gz (30.2 kB view details)

Uploaded Source

Built Distribution

mkchangelog-2.6.0-py3-none-any.whl (27.8 kB view details)

Uploaded Python 3

File details

Details for the file mkchangelog-2.6.0.tar.gz.

File metadata

  • Download URL: mkchangelog-2.6.0.tar.gz
  • Upload date:
  • Size: 30.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for mkchangelog-2.6.0.tar.gz
Algorithm Hash digest
SHA256 9f25791a65562a717889cdddf578e6a91a7f11d9617401279f43932e550c620c
MD5 3c5b8167771325004a06933f9f7d38d7
BLAKE2b-256 e7683e243b1e1176513409fcbbe6a0f35003c3b42b2e9808f0ea8e01522148a9

See more details on using hashes here.

File details

Details for the file mkchangelog-2.6.0-py3-none-any.whl.

File metadata

  • Download URL: mkchangelog-2.6.0-py3-none-any.whl
  • Upload date:
  • Size: 27.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for mkchangelog-2.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a0b7b09c24ec8dcb34764af881875afb155a8ff312c46c44d14c4f63ac7c9bb2
MD5 535dcc57014bf6f95dd3c8d6805e1184
BLAKE2b-256 626e20daca6a61830e8b3bd2b3bf9046cd8b4c0fcdd3fd60b6efc4b11446a2ce

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page