Package: python-kacl
python-kaclA tool for verifying and modifying changelog in theKeep-A-Change-Logformat.python-kaclInstallationFrom SourcePip PackageDockerpre-commitCLICreate a ChangelogVerify a ChangelogPrint the current release versionPrint a single release changelogAdd an entry to an unreleased sectionPrepare a Changelog for a ReleaseLink GenerationSquashing releasesExampleExtensionsPost-release/HotfixConfig fileDevelopmentInstallationpython-kacland itkacl-clican be installed eitherfrom sourcevia the pip packagepython-kacldockerAll approaches are described in detail within this section.From Sourcegitclonehttps://gitlab.com/schmieder.matthias/python-kaclcdpython-kaclGlobal Installpip3install.Developer Modepip3install-e.Pip PackageThe package can simply be retrieves usingpip3installpython-kaclDockerdockerpullmschmieder/kacl-cli:latestThekacl-cliis defined as entrypoint. Therefore the image can be used like thisdocker-v$(pwd):$(pwd)-w$(pwd)mschmieder/kacl-cli:latestverifypre-commitThe 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-kaclrev:'v0.3.0'hooks:-id:kacl-verifyCLIUsage: 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 ChangelogUsage: 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.Usagekacl-clinewCreates the following changelog# ChangelogAll 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).## UnreleasedVerify a ChangelogUsage: 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.Usagekacl-cliverifyJSON Outputkacl-cliverify--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 versionUsagekacl-clicurrent0.1.2Print a single release changelogUsagekacl-cliget0.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 sectionUsage: 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.Usagekacl-cliaddfixed'We fixed some bad issues'--modify
kacl-cliaddadded'We just added some new cool stuff'--modify
kacl-cliaddchanged'And changed things a bit'--modifyPrepare a Changelog for a ReleaseUsage: 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 Supportkacl-cliprovides a direct integration into your git repository. When releasing you often want to directly commit and tag the changes you did.
Using thereleasecommand you can simply add the--commit/--tagoption(s) that will add the changes made by the tool to git. These flags only take effect if you also provide
the--modifyoption, otherwise no change will happen to your file system. By specifying--commit-messageand--tag-descriptionyou can also decide what kind of information you
want to see within the commit. Have a look at theconfigsection that shows more options to use along with thereleasecommand.Messages (--commit-message, --tag-name, --tag-description)This is templated using the Python Format String Syntax. Available in the template context arelatest_versionandnew_versionas well as allenvironment variables(prefixed with $).
You can also use the variablesnoworutcnowto 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 Generationkacl-clican automatically generate links for every version for you. Using the--auto-linkoption will generateversion comparisonlinks for you. The link generation can be configured using theconfigfile. See the config section for more detailskacl-clirelease1.0.0--auto-linkExample output:# ChangelogAll 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#3that 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.0Usage with fixed versionkacl-clirelease1.0.0Example CHANGELOG.md (before):# ChangelogAll 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...HEADExample CHANGELOG.md (after):# ChangelogAll 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...HEADUsage with version incrementkacl-clireleasepatchExample CHANGELOG.md (after):# ChangelogAll 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...HEADLink Generationkacl-clilet's you easily generate links to your versions. You can automatically generate all links following the desired patterns usingkacl-cli link generate.
The link generation can also be easily included into thereleasecommand and will take care of updating theunreleasedandlatest_versionsection.Usage:kacl-clilinkgenerate[OPTIONS]Options:-m,--modifyThisoptionwilladdthechangesdirectlyintochangelogfile.--host-urlTEXTHosturltothegitservice.(i.ehttps://gitlab.com/schmieder.matthias/python-kacl)--compare-versions-templateTEXTTemplatestringforversioncomparisonlink.--unreleased-changes-templateTEXTTemplatestringforunreleasedchangeslink.--initial-version-templateTEXTTemplatestringforinitialversionlink.--helpShowthismessageandexit.Url Templatingin order to generate the correct urls,python-kaclallows you to define three templatescompare-versions-template,unreleased-changes-templateandinitial-version-templatethat 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.ymlconfig filekacl: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-clicompare_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 areversion,previous_version,hostandlatest_version.Squashing releasesIf you are follwing a automated versioning approach, you will often times create a number of versions that might clutter Changelog. For this purpose,kacl-cliprovides asquashcommand 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-versionand--to-versiontokacl-cli squash. Strings passed need to be valid Semantic Versions.Usage:kacl-clisquash[OPTIONS]Squshesallchangesfromagivenversionintoasinglesection.Use'--modify'todirectlymodifythechangelogfile.

Options:-m,--modifyThisoptionwilladdthechangesdirectlyintochangelogfile.--from-versionTEXTTheversiontostartsquashingfrom.[required]--to-versionTEXTTheversiontosquashto.Ifnotgiven,thelatestversionwillbeused.--helpShowthismessageandexit.Examplekacl-cli-fCHANGELOG.mdsquash\--from-version"0.0.1"\--from-version"1.0.0"\--modifyThis example will squash all versions between0.0.1and1.0.0and move them under1.0.0ExtensionsPost-release/HotfixATTENTION:this is not SemVer compatible and not part of the KACL standardIn some situations you might come across the challenge to patch a piece of software that is already in production and youhave toindicate that this is ahotfixrelease.SemVeris not meant to support this other than incrementing thepatchversion of your project, but it is not possible to release1.0.1-hotfix.1after1.0.1as-hotfix.1is considered aprereleaseversion and therefore is lower in order than the1.0.1version.To overcome this,kaclprovides anextensionto you can use in such corner casesYou can enable thepost-releaseextension by providing thepost_release_version_prefixwithin theextensionsecion of your config file. By settingpost_release_version_prefix: hotfixyou can now easily releasehotfixversions that are considered of higher order than the base versionkacl:extension:post_release_version_prefix:hotfix# get current versionkacl-clicurrent
>>0.3.1# add another changekacl-cliaddSecurity"Security Hotfix"-m# release a hotfix versionkacl-clireleasepost-m# get current versionkacl-clicurrent
>>0.3.1-hotfix.1Config filekacl-cliwill automatically check if there is a.kacl.ymlpresent 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 definecustom header titles,allowed_version_sectionsas well as the
requireddefault content.By specifying a.kacl.ymlwith any of those options, thedefault configwill 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 Configkacl:changelog_file:CHANGELOG.mdallowed_header_titles:-Changelog-Change Logallowed_version_sections:-Added-Changed-Deprecated-Removed-Fixed-Securitydefault_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:Truecommit_message:"[skipci]ReleasingChangelogversion{new_version}"commit_additional_files:[]tag:Falsetag_name:"v{new_version}"tag_description:"Versionv{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-clicompare_versions_template:'{host}/compare/{previous_version}...{version}'unreleased_changes_template:'{host}/compare/{latest_version}...master'initial_version_template:'{host}/tree/{version}'auto_generate:Trueextension:post_release_version_prefix:nullDevelopmentWith these instructions you can easily setup a development environment# clone the projectgitclonehttps://gitlab.com/schmieder.matthias/python-kaclcdpython-kacl# create a virtual envpython3-mvenv.venvsource./venv/bin/activate# install in development modepipinstall-e.# install development requirementspipinstall-rdev-requirements# run the testspython3-mpytest--snapshot-update--allow-snapshot-deletion# open VSCodecode.