Pyhton 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.
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://github.com/mschmieder/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
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 changlog.
release Creates a release for the latest 'unreleased' changes.
verify Veryfies if the changelog is in "keep-a-changlog" format.
Create a Changelog
Usage: kacl-cli new [OPTIONS]
Creates a new changlog.
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]
Veryfies if the changelog is in "keep-a-changlog" 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 yaml
--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 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'
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.
-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.
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}')
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://github.com/mschmieder/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://github.com/mschmieder/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://github.com/mschmieder/python-kacl/compare/v1.0.0...HEAD
Project details
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
File details
Details for the file python-kacl-0.2.11.tar.gz
.
File metadata
- Download URL: python-kacl-0.2.11.tar.gz
- Upload date:
- Size: 15.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/42.0.2 requests-toolbelt/0.9.1 tqdm/4.41.0 CPython/3.6.7
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
5051b52dd4eff4553ef2fc93a8643892c5fca4f6a951fe96b9528b7e29086f81
|
|
MD5 |
e24648fe01233d3302bff6c9789c9422
|
|
BLAKE2b-256 |
7a87d8c0692eeb174fe39d7f172006eb37be8f29b9ac3a2ee440dc09141acd79
|