python-kacl 0.4.2

Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"

python-kacl

![Build Status](https://gitlab.com/schmieder.matthias/python-kacl/badges/main/pipeline.svg?ignore_skipped=true

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

• python-kacl
  • Installation
    • From Source
    • Pip Package
    • Docker
    • pre-commit
  • CLI
  • Create a Changelog
  • Verify a Changelog
  • Print the current release version
  • Print a single release changelog
  • Add an entry to an unreleased section
  • Prepare a Changelog for a Release
  • Link Generation
  • Extensions
    • Post-release/Hotfix
  • Config file
  • Development

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

- repo: https://gitlab.com/schmieder.matthias/python-kacl
  rev: 'v0.3.0'
  hooks:
    - id: kacl-verify

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.
  verify   Verifies if the changelog is in "keep-a-changelog" format.

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. 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

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'

  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

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:
  git:
    links:
        # The host url is optional and will be automatically determined using your the git repository. If run on gitlab CI the host will be determined by CI_PROJECT_URL if not specified here.
        host_url: https://github.com/mschmieder/kacl-cli
        compare_versions_template: '{host}/compare/v{previous_version}...v{version}'
        unreleased_changes_template: '{host}/tree/v{latest_version}...HEAD'
        initial_version_template: '{host}/tree/v{version}'

Using the python format syntax you can generate any links you want. The available replacement variables are version, previous_version, host and latest_version.

Extensions

Post-release/Hotfix

ATTENTION: this is not SemVer compatible and not part of the KACL standard

In some situations you might come across the challenge to patch a piece of software that is already in production and you have to indicate that this is a hotfix release. SemVer is not meant to support this other than incrementing the patch version of your project, but it is not possible to release 1.0.1-hotfix.1 after 1.0.1 as -hotfix.1 is considered a prerelease version and therefore is lower in order than the 1.0.1 version.

To overcome this, kacl provides an extension to you can use in such corner cases

You can enable the post-release extension by providing the post_release_version_prefix within the extension secion of your config file. By setting post_release_version_prefix: hotfix you can now easily release hotfix versions that are considered of higher order than the base version

kacl:
  extension:
    post_release_version_prefix: hotfix

# get current version
kacl-cli current
>> 0.3.1

# add another change
kacl-cli add Security "Security Hotfix" -m

# release a hotfix version
kacl-cli release post -m

# get current version
kacl-cli current
>> 0.3.1-hotfix.1

Config file

kacl-cli will automatically check if there is a .kacl.yml present within your execution directory. Within this configuration file you can set options to improve specifically CI workflows. It also allows you to better customize the validation behaviour of the system by allowing to define custom header titles, allowed_version_sections as well as the required default content.

By specifying a .kacl.yml with any of those options, the default config will be merged with those local changes. Most options are also available on the CLI which take precedence over the ones within the config files.

Default Config

kacl:
  changelog_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: True
    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:
      # The host url is optional and will be automatically determined using your the git repository
      # host_url: https://github.com/mschmieder/kacl-cli
      compare_versions_template: '{host}/compare/{previous_version}...{version}'
      unreleased_changes_template: '{host}/compare/{latest_version}...master'
      initial_version_template: '{host}/tree/{version}'
      auto_generate: True
  extension:
    post_release_version_prefix: null

Development

With these instructions you can easily setup a development environment

# clone the project
git clone https://gitlab.com/schmieder.matthias/python-kacl
cd python-kacl

# create a virtual env
python3 -m venv .venv
source ./venv/bin/activate

# install in development mode
pip install -e .

# install development requirements
pip install -r dev-requirements

# run the tests
python3 -m pytest --snapshot-update --allow-snapshot-deletion

# open VSCode
code .