atwalsh / kac

Python and CLI tool for CHANGELOG files that follow the Keep a Changelog standard.

kac

Python and CLI tool for CHANGELOG files that follow the Keep a Changelog standard.

Installation

pip install kac

CLI

Run kac in the same directory as your Changelog. By default, kac looks for a file called CHANGELOG.md (case-insensitive).

Usage: kac [OPTIONS] COMMAND [ARGS]...

  Python and  CLI tool for CHANGELOG files that follow the Keep a Changelog
  standard.

Options:
  --help  Show this message and exit.

Commands:
  bump  Bump the latest version of a CHANGELOG file.
  copy  Copy the latest release's changelog text.
  init  Create an empty CHANGELOG file.

API

Changelog

Create a Changelog object:

>>> from kac.changelog import Changelog
>>> Changelog('CHANGELOG.md')
<CHANGELOG v0.5.0>

Interact with a Changelog:

>>> from kac.changelog import Changelog
>>> changelog = Changelog('/path/to/CHANGELOG.md')
>>> changelog.latest_version
VersionInfo(major=0, minor=5, patch=0, prerelease=None, build=None)

>>> changelog.latest_release
<Release v0.5.0 - 2021-09-11>

>>> changelog.latest_release.added # Get a list of changes for latest release
['`-t/--type` option for `bump` command']

Limitations

• Must be run in the same directory as your CHANGELOG file
• Only works for semver
• kac bump can "format" (ex: remove extra empty lines) CHANGELOG files, this could be unfavorable for users

kac's Issues

Extra new lines on `kac copy`

There seems to be extra newlines at the end of the text copied during the kac copy command.

"No notable changes"

Add "No notable changes" to a release section if there were no updates in the Unreleased section.

Switch CI/CD to GitHub actions

Dependabot pull requests

It would be nice of kac could automatically update a repo's CHANGELOG when a dependable PR get's merged. Ideally, kac would add a commit to the existing dependabot PR so that an additional PR does not need to be created after the dependabot PR is merged.

Fix PyPI release action

https://github.com/atwalsh/kac/actions/runs/559561459

Update PyPI description and other attributes

Update pyproject.toml to include additional attributes visible on PyPI page: README, repo link, etc.

Stop pinning dependency versions in setup.py

Make the regex markdown linter compliant

Markdown linters expect a line jump after titles.

Your current code parses this:

# Changelog

## [Unreleased]
### Added

- Nothing

[Unreleased]: https://github.com/atwalsh/kac/compare/v0.0.1...HEAD
[0.0.1]: https://git[0.0.1]: https://github.com/atwalsh/

We can check it easily:

from kac.changelog import Changelog

my_changelog = Changelog(
    r"C:\Users\f400411\Documents\PERSONAL\PROJECTS\BUG_REPORTS\kac\CHANGELOG.md"
)

my_changelog.unreleased.added #  ["Nothing"]

but it fails to parse this:

# Changelog

## [Unreleased]
                          <-extra line jump here 
### Added

- Nothing

[Unreleased]: https://github.com/atwalsh/kac/compare/v0.0.1...HEAD
[0.0.1]: https://git[0.0.1]: https://github.com/atwalsh/

from kac.changelog import Changelog

my_changelog = Changelog(
    r"C:\Users\f400411\Documents\PERSONAL\PROJECTS\BUG_REPORTS\kac\CHANGELOG.md"
)

my_changelog.unreleased.added #  []

Hence the kac bump command is broken. The fix would be to have an extra "\n?" here:

https://github.com/atwalsh/kac/blob/master/kac/changelog/changelog.py#L43

A more informative error message would be helpful too, to avoid the need to dig in the code to understand what is going on.

`kac copy` copies footer content on initial version

Running the kac copy command on the first version in a changelog (ex: after kac template) copies the repository URL links.

kac bump should use the package version

The current CLI prompts us to choose the new version number. This is definitely something which prevents the adoption of the tool from a CI/CD perspective: I wish I could use the command kac bump inside, say, a github action and either:

• specify which version part to increment in CLi (e.g. kac bump --type=minor)
• Do not specify anything and use the package version inside the __init__.py (we should check that the version is different from the last knwon one). This will make kac compatible with bump2version.

Better way to test files generation / expected output

Storing a bunch of .md files in the tests/ directory seems bad. Try to figure out a better way to test expected file output and compare modified CHANGELOG files.

Retrieve the git url from git metadata instead of manually

In a versioned folder, we have a .git folder and we can use the git remote -vv command to retrieve the git url of the project's changelogautomatically . This would avoid providing it manually (as it is currently done in kac init).

GitHub actions

There are a bunch of enhancements the tool could bring to an automated deployment process, ex:

• Auto-release the latest CHANGELOG version after merging PRs that have a release label
• Checking the format of a CHANGELOG file
• Checking that a CHANGELOG has been modified before a PR can be merged

`kac commit`

Auto-generate commit for changelog updates.

Copy version tag text to clipboard

Add copy command that allows copying the tag text of the latest version (if no version number is passed) or a specific version number (if the user passes a version):

# Changelog at v3.7.0
$ kac copy
v3.7.0 tag text copied to clipboard!

A similar feature was described in: olivierlacan/keep-a-changelog#51 (comment)

Possibly use https://github.com/asweigart/pyperclip

`kac init` generate an invalid CHANGELOG file

Hi @atwalsh,

I am not sure if this repo is still maintained, but I wanted to build a CLI tools very similar to yours to handle changelog, and I'd like to contribute to your project to avoid reinventing the wheel. This issue is the first one of a list of all the bugs I discover will trying to set it up.

The first bug is that the kac init command generates an invalid Changelog file: the date is missing, hence you do not parse it.

Code to reproduce:

In an empty project:

kac init

Type enter twice to define the 1st version and the default github url.

from kac.changelog import Changelog

my_changelog = Changelog(
    r"CHANGELOG.md"
)

print(my_changelog) # raise an out of range error

Hence, none of your commands work (especially kac bump). This is due to this line of the template having no "- date" part, hence this regex fails to parse it. the fix would be to add the date in the template.