Sign inSign up

mschmieder/kacl-cli

By mschmieder

•Updated about 1 month ago

Image
0

9.5K

mschmieder/kacl-cli repository overview

⁠python-kacl

Build Status Coverage Code Smells Maintainability Rating

A tool for verifying and modifying changelog in the Keep-A-Change-Log⁠ format.

⁠Installation

python-kacl and it kacl-cli can be installed either

  • from source
  • via the pip package python-kacl
  • docker

All approaches are described in detail within this section.

⁠From Source
git clone https://gitlab.com/schmieder.matthias/python-kacl
cd python-kacl

Global Install

pip3 install .

Developer Mode

pip3 install -e .
⁠Pip Package

The package can simply be retrieves using

pip3 install python-kacl
⁠Docker
docker pull mschmieder/kacl-cli:latest

The kacl-cli is defined as entrypoint. Therefore the image can be used like this

docker -v $(pwd):$(pwd) -w $(pwd) mschmieder/kacl-cli:latest verify
⁠pre-commit

The package can also be used as a pre-commit hook. Just add the following to your .pre-commit-config.yaml

Verify Changelog Format

- repo: https://gitlab.com/schmieder.matthias/python-kacl
  rev: 'v0.7.0'  # Use the latest version
  hooks:
    - id: kacl-verify

Auto-Stash Unreleased Changes (Prevent Merge Conflicts)

- repo: https://gitlab.com/schmieder.matthias/python-kacl
  rev: 'v0.7.0'  # Use the latest version
  hooks:
    - id: kacl-stash

The kacl-stash hook automatically moves unreleased changes to stash files before each commit, preventing merge conflicts in CHANGELOG.md. See Stashing Unreleased Changes⁠ for more details.

⁠CLI

Usage: kacl-cli [OPTIONS] COMMAND [ARGS]...

Options:
  -c, --config PATH  Path to kacl config file  [default: .kacl.conf]
  -f, --file PATH    Path to changelog file  [default: CHANGELOG.md]
  --help             Show this message and exit.

Commands:
  add      Adds a given message to a specified unreleased section.
  get      Returns a given version from the Changelog
  new      Creates a new changelog.
  release  Creates a release for the latest 'unreleased' changes.
  stash    Moves all unreleased changes from the changelog to the stash.
  verify   Verifies if the changelog is in "keep-a-changelog" format.

⁠Initialize a new project

Usage: kacl-cli init [OPTIONS]

  Initializes a project with all necessary kacl setting.

Options:
  -f, --force  Will overwrite existing files.
  --help       Show this message and exit.

The init command provides a quick way to set up a new project with all necessary KACL files and configuration. This command creates two essential files:

  1. CHANGELOG.md - A new changelog file with the standard Keep a Changelog format
  2. .kacl.yml - A complete configuration file with all available options and sensible defaults

Usage

kacl-cli init

This will create both files in the current directory. If either file already exists, the command will fail unless you use the --force option:

kacl-cli init --force

Created Files

The init command creates a standard CHANGELOG.md file and copies the complete default configuration. The .kacl.yml file includes all available configuration options:

kacl:
  file: CHANGELOG.md
  allowed_header_titles:
    - Changelog
    - Change Log
  allowed_version_sections:
    - Added
    - Changed
    - Deprecated
    - Removed
    - Fixed
    - Security
  default_content:
    - 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.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
  git:
    commit: False
    commit_message: "[skip ci] Releasing Changelog version {new_version}"
    commit_additional_files: []
    tag: False
    tag_name: "v{new_version}"
    tag_description: "Version v{new_version} released"
  links:
    auto_generate: False
    compare_versions_template: '{host}/compare/{previous_version}...{version}'
    unreleased_changes_template: '{host}/compare/{latest_version}...master'
    initial_version_template: '{host}/tree/{version}'
  extension:
    post_release_version_prefix: null
  issue_tracker:
    jira:
      host: null
      username: null
      password: null
      issue_patterns: ["[A-Z]+-[0-9]+"]
      comment_template: |
        # 🚀 New version [v{new_version}]({link})

        A new release has been created referencing this issue. Please check it out.

        ## 🚧 Changes in this version

        {changes}

        ## 🧭 Reference

        Code: [Source Code Management System]({link})
  stash:
    directory: .kacl_stash
    always: False

You can customize any of these settings according to your project's needs. The configuration provides sensible defaults that work for most projects while offering extensive customization options for advanced use cases.

⁠Create a Changelog

Usage: kacl-cli new [OPTIONS]

  Creates a new changelog.

Options:
  -o, --output-file PATH  File to write the created changelog to.
  --help                  Show this message and exit.

Usage

kacl-cli new

Creates the following changelog

# 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.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased

⁠Verify a Changelog

Usage: kacl-cli verify [OPTIONS]

  Verifies if the changelog is in "keep-a-changelog" format. Use '--json' get
  JSON formatted output that can be easier integrated into CI workflows.
  Exit code is the number of identified errors.

Options:
  --json  Print validation output as json
  --help  Show this message and exit.

Usage

kacl-cli verify

JSON Output

kacl-cli verify --json

{
    "errors": [
        {
            "end_character_pos": 8,
            "error_message": "Versions need to be decorated with a release date in the following format 'YYYY-MM-DD'",
            "line": "## 1.0.0",
            "line_number": 8,
            "start_char_pos": 0
        },
        {
            "end_character_pos": 10,
            "error_message": "\"Hacked\" is not a valid section for a version. Options are [Added,Changed,Deprecated,Removed,Fixed,Security]",
            "line": "### Hacked",
            "line_number": 12,
            "start_char_pos": 4
        }
    ],
    "valid": false
}

⁠Print the current release version

Usage

kacl-cli current

0.1.2

⁠Print a single release changelog

Usage

kacl-cli get 0.2.2

## [0.2.2] - 2018-01-16

### Added

- Many prior version. This was added as first entry in CHANGELOG when it was added to this project.

⁠Add an entry to an unreleased section

Usage: kacl-cli add [OPTIONS] SECTION MESSAGE

  Adds a given message to a specified unreleased section. A new unreleased
  section is added if it doesn't exist. Use '--modify' to directly modify
  the changelog file.

Options:
  -m, --modify  This option will add the changes directly into changelog file
  --help        Show this message and exit.

Usage

kacl-cli add fixed 'We fixed some bad issues' --modify
kacl-cli add added 'We just added some new cool stuff' --modify
kacl-cli add changed 'And changed things a bit' --modify

⁠Stashing Unreleased Changes

Usage: kacl-cli stash [OPTIONS]

  Moves all unreleased changes from the changelog to the stash.

Options:
  -m, --modify  This option will modify the changelog file directly.
  --help        Show this message and exit.

The stash command provides a powerful solution for managing unreleased changes and preventing merge conflicts in collaborative development environments. It moves all unreleased changes from CHANGELOG.md to a stash file, leaving an empty "Unreleased" section in the main changelog.

Primary Use Case: Avoiding Merge Conflicts

When multiple team members work on different branches simultaneously and manually edit CHANGELOG.md, merge conflicts are inevitable. The stash command solves this problem by:

  1. Moving changes out of the main changelog into separate stash files
  2. Preventing conflicts during merges since the main changelog remains minimal
  3. Preserving all changes in stash files that are later consolidated during release

Usage

# Preview what would be stashed (dry-run)
kacl-cli stash

# Actually stash the changes and update CHANGELOG.md
kacl-cli stash --modify

How It Works

When you run kacl-cli stash --modify:

  1. All changes from the "Unreleased" section are extracted
  2. Changes are moved to a stash file in .kacl_stash/ directory (default location)
  3. Stash files are named based on:
    • Git branch name (when inside a git repository): feature-branch.md
    • Current date (when outside git): 20230101.md
  4. The "Unreleased" section in CHANGELOG.md is cleared
  5. During kacl-cli release, all stashed changes are automatically merged into the release

Example Workflow

# Developer edits CHANGELOG.md directly
echo "- Added new feature" >> CHANGELOG.md

# Before committing, stash the changes to avoid conflicts
kacl-cli stash --modify

# CHANGELOG.md now has an empty Unreleased section
# Changes are in .kacl_stash/your-branch.md

# When ready to release, all stashed changes are included
kacl-cli release patch --modify
⁠Pre-commit Hook Integration

For maximum convenience, you can automate the stashing process using a pre-commit hook. This allows developers to continue editing CHANGELOG.md manually while automatically moving changes to the stash before each commit.

Setup

Add the kacl-stash hook to your .pre-commit-config.yaml:

repos:
  - repo: https://gitlab.com/schmieder.matthias/python-kacl
    rev: 'v0.7.0'  # Use the latest version
    hooks:
      - id: kacl-stash

How It Works

  1. Developer manually edits CHANGELOG.md (traditional workflow)
  2. Pre-commit hook automatically runs kacl-cli stash -m before each commit
  3. Changes are moved to stash files
  4. Only the cleaned CHANGELOG.md is committed
  5. Multiple branches can work independently without conflicts
  6. During release, all stashed changes are consolidated

Benefits

  • ✅ No workflow changes: Developers continue editing CHANGELOG.md normally
  • ✅ Zero merge conflicts: Main changelog stays minimal and conflict-free
  • ✅ Automatic management: Pre-commit hook handles everything
  • ✅ Branch isolation: Each branch has its own stash file
  • ✅ Seamless integration: Changes automatically included in releases

Configuration

You can customize the stash directory in .kacl.yml:

kacl:
  stash:
    dir: .kacl_stash  # Custom stash directory
    always: False     # Set to True to always use stash for 'kacl add'

Note: The stash command is complementary to Changelog Fragments⁠. While fragments support the kacl add workflow, the stash command is specifically designed for teams that prefer manually editing CHANGELOG.md but want to avoid merge conflicts.

⁠Prepare a Changelog for a Release

Usage: kacl-cli release [OPTIONS] VERSION

  Creates a release for the latest 'unreleased' changes. Use '--modify' to
  directly modify the changelog file. You can automatically use the latest
  version by using the version keywords 'major', 'minor', 'patch', 'post'.
  Creates a new empty unreleased section if not disabled in the configuration
  file.

  Example:

      kacl-cli release 1.0.0

      kacl-cli release major|minor|patch

Options:
  -m, --modify            This option will add the changes directly into
                          changelog file.
  -l, --link TEXT         A url that the version will be linked with.
  -g, --auto-link         Will automatically create and update necessary
                          links.
  -c, --commit            If passed this will create a git commit with the
                          changed Changelog.
  --commit-message TEXT   The commit message to use when using --commit flag
  -t, --tag               If passed this will create a git tag for the newly
                          released version.
  --tag-name TEXT         The tag name to use when using --tag flag
  --tag-description TEXT  The tag description text to use when using --tag
                          flag
  -d, --allow-dirty       If passed this will allow to commit/tag even on a
                          "dirty".
  --help                  Show this message and exit.

Git Support

kacl-cli provides a direct integration into your git repository. When releasing you often want to directly commit and tag the changes you did. Using the release command you can simply add the --commit/--tag option(s) that will add the changes made by the tool to git. These flags only take effect if you also provide the --modify option, otherwise no change will happen to your file system. By specifying --commit-message and --tag-description you can also decide what kind of information you want to see within the commit. Have a look at the config section that shows more options to use along with the release command.

Messages (--commit-message, --tag-name, --tag-description)

This is templated using the Python Format String Syntax. Available in the template context are latest_version and new_version as well as all environment variables (prefixed with $). You can also use the variables now or utcnow to get a current timestamp. Both accept datetime formatting (when used like as in {now:%d.%m.%Y}). Also available as --message (e.g.: kacl-cli release patch --commit --commit--message '[{now:%Y-%m-%d}] Jenkins Build {$BUILD_NUMBER}: {new_version}')

Auto Link Generation

kacl-cli can automatically generate links for every version for you. Using the --auto-link option will generate version comparison links for you. The link generation can be configured using the config file. See the config section for more details

kacl-cli release 1.0.0 --auto-link

Example output:

# 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.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2020-01-14
### Added
- `release` command will make sure changelog is valid before doing any changes.

## 0.2.16 - 2020-01-07
### Fixed
- fixed issue #3 that did not detect linked versions with missing links

[Unreleased]: https://gitlab.com/schmieder.matthias/python-kacl/tree/v1.0.0...HEAD
[1.0.0]: https://gitlab.com/schmieder.matthias/python-kacl/compare/v0.2.16...v1.0.0

Usage with fixed version

kacl-cli release 1.0.0

Example CHANGELOG.md (before):

# 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.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
### Added
- added default content checks
- cli will now check for valid semantic version when using `release` command
- implemented basic cli with `new`, `get`, `release`, `verify`
- added `--json` option to `verify` command

## 0.1.0 - 2019-12-12
### Added
- initial release

[Unreleased]: https://gitlab.com/schmieder.matthias/python-kacl/compare/v1.0.0...HEAD

Example CHANGELOG.md (after):

# 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.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## 1.0.0 - 2019-12-22
### Added
- added default content checks
- cli will now check for valid semantic version when using `release` command
- implemented basic cli with `new`, `get`, `release`, `verify`
- added `--json` option to `verify` command

## 0.1.0 - 2019-12-12
### Added
- initial release

[Unreleased]: https://gitlab.com/schmieder.matthias/python-kacl/compare/v1.0.0...HEAD

Usage with version increment

kacl-cli release patch

Example CHANGELOG.md (after):

# 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.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## 0.1.1 - 2019-12-22
### Added
- added default content checks
- cli will now check for valid semantic version when using `release` command
- implemented basic cli with `new`, `get`, `release`, `verify`
- added `--json` option to `verify` command

## 0.1.0 - 2019-12-12
### Added
- initial release

[Unreleased]: https://gitlab.com/schmieder.matthias/python-kacl/compare/v1.0.0...HEAD

⁠Changelog Fragments

kacl-cli supports "changelog fragments" starting from version 6.6.0, which provides a powerful solution for managing unreleased changes in collaborative development environments. This feature helps avoid merge conflicts and simplifies changelog management when multiple developers are working on different branches simultaneously.

⁠Configuration

Enable changelog fragments through the .kacl.yml configuration file:

kacl:
  stash:
    dir: .kacl_stash
    always: True

Configuration Options:

  • dir: Directory where changelog fragments are stored (default: .kacl_stash)
  • always: When True, all kacl add commands automatically create fragments instead of modifying the main changelog
⁠How It Works

The stash functionality stores "Unreleased" changes in separate fragment files within the configured stash directory. These fragment files are git-branch aware:

  • Inside a git repository: Fragment files are named {git_branch}.md
  • Outside a git repository: Fragment files use a timestamp-based name

This branch-aware naming ensures maximum segregation of changes, preventing merge conflicts and rebase issues that commonly occur when multiple merge requests modify the same changelog file simultaneously.

⁠Usage Patterns
⁠Automatic Fragment Creation

With always: True in your configuration, all changelog additions are automatically directed to fragments:

kacl add -m Changed "my new changelog entry"

This command creates or updates a fragment file (e.g., feature-branch.md) instead of modifying the main CHANGELOG.md.

⁠Manual Fragment Control

With always: False, you have explicit control over where changes are added:

# Add directly to CHANGELOG.md
kacl add -m Changed "directly to the CHANGELOG.md"

# Add to a fragment file
kacl add -m --stash Changed "into the fragment"
⁠Fragment Structure

Each fragment file contains a standard changelog structure:

# 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.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased
### Changed
- my new changelog entry
⁠Release Integration

When executing kacl release, the system automatically:

  1. Collects all fragments from the stash directory
  2. Merges fragment content into the main changelog under the new release version
  3. Deletes processed fragments from the stash directory
  4. Stages deletions in git so fragments are removed when the release is committed

This seamless integration ensures that all distributed changes across branches are consolidated into a single release entry.

⁠Workflow Integration

Changelog fragments are fully integrated into all kacl workflows:

  • kacl verify: Validates both the main changelog and all fragments
  • kacl get: Considers fragment content when retrieving version information
  • Git operations: Fragment cleanup is automatically handled during release commits
⁠Benefits
  • Eliminates merge conflicts on changelog files
  • Enables parallel development without coordination overhead
  • Maintains changelog quality through individual fragment validation
  • Simplifies release process with automatic fragment consolidation
  • Preserves git history of changelog contributions per branch

⁠Link Generation

kacl-cli let's you easily generate links to your versions. You can automatically generate all links following the desired patterns using kacl-cli link generate. The link generation can also be easily included into the release command and will take care of updating the unreleased and latest_version section.

Usage: kacl-cli link generate [OPTIONS]

Options:
  -m, --modify                    This option will add the changes directly
                                  into changelog file.
  --host-url TEXT                 Host url to the git service. (i.e
                                  https://gitlab.com/schmieder.matthias/python-kacl)
  --compare-versions-template TEXT
                                  Template string for version comparison link.
  --unreleased-changes-template TEXT
                                  Template string for unreleased changes link.
  --initial-version-template TEXT
                                  Template string for initial version link.
  --help                          Show this message and exit.

Url Templating

in order to generate the correct urls, python-kacl allows you to define three templates compare-versions-template, unreleased-changes-template and initial-version-template that can be used to tell the system how to generate proper links. The easiest way to provide this information is to pass it to the .kacl.yml config file

kacl:
  links:
    # The host url is optional and will be automatically determined using your git repository. If run on gitlab CI the host will be determined by CI_PROJECT_URL if not speci

Tag summary

Content type

Image

Digest

sha256:ff8ed585b…

Size

43.3 MB

Last updated

about 1 month ago

docker pull mschmieder/kacl-cli