Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"
Project description
python-kacl
A tool for verifying and modifying changelog in the Keep-A-Change-Log format.
- python-kacl
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:
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 specified here.
host_url: https://github.com/mschmieder/kacl-cli
compare_versions_template: '{host}/compare/v{previous_version}...v{version}'
unreleased_changes_template: '{host}/compare/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.
Squashing releases
If you are follwing a automated versioning approach, you will often times create a number of versions that might clutter Changelog. For this purpose, kacl-cli provides a squash command that let's you squash releases into a single one without loosing valuable information.
To squash the versions, you will need to specify the version range to squash by passing --from-version and --to-version to kacl-cli squash. Strings passed need to be valid Semantic Versions.
Usage: kacl-cli squash [OPTIONS]
Squshes all changes from a given version into a single section. Use '--
modify' to directly modify the changelog file.
Options:
-m, --modify This option will add the changes directly into
changelog file.
--from-version TEXT The version to start squashing from. [required]
--to-version TEXT The version to squash to. If not given, the latest
version will be used.
--help Show this message and exit.
Example
kacl-cli -f CHANGELOG.md squash \
--from-version "0.0.1" \
--from-version "1.0.0" \
--modify
This example will squash all versions between 0.0.1 and 1.0.0 and move them under 1.0.0
Issue Management Integration
With python-kacl >= 0.6.0, you can integrate changelog and release management directly into your Issue Management System. Currently, the supported system is JIRA.
It is common practice to reference fixed or addressed issues in the changelog, as shown below:
## Unreleased
### Added
- JIRA-1754 Just unreleased stuff
## 1.0.0 - 2017-06-20
### Added
- JIRA-9: added UI functionality
### Fixed
- issue JIRA-13 closed by applying the solution
Adding Comments to Issues
The add-comments command allows you to detect issue IDs using a custom pattern and create comments in the Issue Tracking system about a new release.
You can pass all necessary arguments via CLI or set up your .kacl.yaml configuration file. The following options are available:
issue_tracker:
jira:
host: jira.atlassian.com # The host name of your JIRA instance
username: null # The username to login. Uses JIRA_USERNAME environment variable if available
password: null # The password to login. Uses JIRA_PASSWORD environment variable if available
issue_patterns: # List of regex patterns to identify the issues
- "[A-Z]+-[0-9]+"
- "JIRA-[0-9]+"
comment_template: | # A text template used to comment on the issue
# 🚀 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})
Run the following command to create the comments:
kacl-cli add-comments 1.0.0
Command Options
See all available command options:
Usage: kacl-cli add-comments [OPTIONS] VERSION
Adds comments to issues identified within the CHANGELOG. Currently
supported system: JIRA
Options:
--jira-username TEXT JIRA username. Will also look for the
JIRA_USERNAME environment variable.
--jira-password TEXT JIRA password. Will also look for the
JIRA_PASSWORD environment variable.
--jira-host TEXT JIRA host. Will also look for the JIRA_HOST
environment variable.
--jira-issue-pattern TEXT Issue pattern to search the changelog for. Can
be specified multiple times.
--jira-comment-template TEXT JIRA comment template.
--fail Fail if comments could not be added.
--help Show this message and exit.
Templating the Comment
The comment_template parameter allows various templating options. The following template variables are available:
| Variable | Description |
|---|---|
new_version |
The version that was just released |
changes |
The markdown content within the change section of your CHANGELOG |
link |
The link to the version within your source code management system according to the link configuration |
env.MYENVVAR |
Any environment variable |
This flexibility allows you to adapt the comment patterns to your needs and dynamically create them. For example, adding CI/CD information can be easily achieved as follows:
comment_template: | # A text template used to comment on the issue
# 🚀 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})
Pipeline: [Pipeline ({env.CI_PIPELINE_IID})]({env.CI_PIPELINE_URL})
GitLab Project: [({env.CI_PROJECT_TITLE})]({env.CI_PROJECT_URL})
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 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
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})
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.txt
# run the tests
python3 -m pytest --snapshot-update --allow-snapshot-deletion
# open VSCode
code .
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for python_kacl-0.6.2-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 7cbc4848cd7d6f40fef9efc189c65009904cfd7eb3418846a30720db9feae82e |
|
| MD5 | 5a1eb8431624852baf64baa8602b55ed |
|
| BLAKE2b-256 | 73a1175fda52bb4bb002dd21d3c51826a265b0e628177fd8efe1240b70d2d6d4 |
