🦊 Foxy changelog

A tool which generates a changelog and manage version for any git repository using conventional commits specification.

• Installation
• Changelog generation
  • Add to an existing changelog
• Version management
  • semver-conventional-commit-foxy
  • calendar-conventional-commit-foxy
  • Hatch
• Configuration
  • Python project
  • Other projects
• Command line interface

Installation

It is recommanded to install this tool with pipx to install it in a isolated environments:

pipx install foxy-changelog

Changelog generation

Add to an existing changelog

If you’d like to keep an existing changelog below your generated one, just add <!-- foxy-changelog-above --> to your current changelog. The generated changelog will be added above this token, and anything below will remain.

Version management

foxy-changelog is providing support to automatically generate the version of your python project according to its commit history.

The management is based on setuptools_scm and conventional commit.

As defined in the conventional commit specification:

• The type feat MUST be used when a commit adds a new feature to your application or library.
• The type fix MUST be used when a commit represents a bug fix for your application.

foxy-changelog is providing two entry points for setuptools_scm.version_scheme configuration.

semver-conventional-commit-foxy

Based on semver.

Rules:

• A commit with type feat activates an increment of the minor.
• All other types will activate an increment of the patch.

calendar-conventional-commit-foxy

To manage version based on the calendar. The supported convention is YYYY.MM.Patch with Patch a number not 0-padded starting to 1. (example: 2024.01.1).

Rules:

• A commit with type feat activates an increment of the month.
• All other types will activate an increment of the patch version.
• The year is automatically incremented at the end a year.

Hatch

Hatch is supporting out of the box thanks to hatch-vcs. Python projet using other project management tool can use setuptools_scm directly.

Ensure hatch-vcs and foxy-changelog is defined within the build-system.requires field in your pyproject.toml file.

All other options supported by hatch-vcs and setuptools_scm can be used. More information can be found in their documentation.

[build-system]
requires = ["hatchling", "hatch-vcs", "foxy-changelog"]
build-backend = "hatchling.build"

[tool.hatch.version]
source = "vcs"

[tool.hatch.version.raw-options]
version_scheme = "semver-conventional-commit-foxy"

Configuration

foxy-changelog can be configured thanks to its command line or configuration files (foxy-changelog.toml or pyproject.toml). All the configurations of the command line to be also put in the configuration files for easier usage.

Configurations files are automatically looked up in the project's folder but custom path can always to passed to the command line. Configurations from different sources are considered with an defined order. Commande line options overrides configurations from foxy-changelog.toml which overrides configurations from pyproject.toml.

Python project

pyproject.toml is supported and is the recommanded way to configure python projects.

The following configuration block can be added to the pyproject.toml file.

[tool.foxy-changelog.changelog]
tag_pattern = "semver"

If no title and description are provided the one from project configuration are taken.

Other projects

foxy-changelog.toml is recommanded way.

The following configuration block can be added to the foxy-changelog.toml file.

[changelog]
tag_pattern = "semver"

Command line interface

You can list the command line options by running foxy-changelog --help:

Usage: foxy-changelog [OPTIONS]

Options:
-c, --config PATH          path to 'pyproject.toml' with foxy-changelog
                           config or 'foxy-changelog.toml' , default: looked
                           up in the current or parent directories
--gitlab                   Set Gitlab Pattern Generation.
--github                   Set GitHub Pattern Generation.
-p, --path-repo PATH       Path to the repository's root directory
                           [Default: .]

-t, --title TEXT           The changelog's title [Default: Changelog]
-d, --description TEXT     Your project's description
-o, --output FILENAME      The place to save the generated changelog
                           [Default: CHANGELOG.md]

-r, --remote TEXT          Specify git remote to use for links
-v, --latest-version TEXT  use specified version as latest release
-u, --unreleased           Include section for unreleased changes
--template TEXT            specify template to use [compact, lastrelease] or a path
                           to a custom template, default: compact

--diff-url TEXT            override url for compares, use {current} and
                           {previous} for tags

--issue-url TEXT           Override url for issues, use {id} for issue id
--issue-pattern TEXT       Override regex pattern for issues in commit
                           messages. Should contain two groups, original
                           match and ID used by issue-url.

--tag-pattern TEXT         Specify regex pattern for version tags [semver,
                           calendar, custom-regex]. A custom regex containing
                           one group named 'version' can be specified.
                           [default: semver]

--tag-prefix TEXT          prefix used in version tags, default: ""
--stdout
--tag-pattern TEXT         Override regex pattern for release tags
--starting-commit TEXT     Starting commit to use for changelog generation
--stopping-commit TEXT     Stopping commit to use for changelog generation
--debug                    set logging level to DEBUG
--help                     Show this message and exit.