Keepac
Named after the first few letters of keepachangelog.com.
The Keep a Changelog best practises provide a solid foundation when writing changelogs. This way, you can concentrate on writing the changelog itself.
Keepac helps you work with changelogs following these conventions.
Its binary, changelog, makes all commands feel natural.
Example workflow
Let’s walk through common software development steps to show how Keepac can help us documenting the user-facing changes.
The command line blocks show the commands and their respective output.
Below the commands you also see the diff of the CHANGELOG.md file.
Creating The Changelog File
Now imagine you have already created your project using something like cargo new, npm create, or something else.
Since we are very disciplined developers, we start documenting our changes right away.
$ changelog init
Initialized empty changelog at /tmp/keepac-demo/CHANGELOG.md:
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.1.0/, and this project adheres to Semantic Versioning https://semver.org/spec/v2.0.0.html. ## [Unreleased]
# 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.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]That was easy! We did not even have to open our IDE or text editor.
If you use git on the command line, this workflow feels very similar to git init.
This is on purpose.
While the git CLI is not known for being intuitive, it has some nice features that inspired changelog.
Documenting Changes
Now imagine we have implement a new feature.
The details are not important, just imagine we added a new API that our users should know about.
Again, we use changelog for this, directly from our terminal.
$ changelog add "A shiny new feature"
### Added • A shiny new feature # 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.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- A shiny new featureSimilar to git, if you omit the message, your $EDITOR would open and you could provide more detail.
Removing, Changing, Or Deprecating Features
In our fictional example, it won’t really make sense to document the removal of features. However, the Keep a Changelog guidelines list several types of changes, such as bug fixes, deprecations or general changes in behavior of the software. Let’s document the removal of an old feature that we no longer want to support, just to see how that would work.
$ changelog rm "A boring old feature"
### Removed • A boring old feature # 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.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- A shiny new feature
### Removed
- A boring old featureInstead of using the shortcuts (add, change, deprecate, …), you may also run the generic changelog insert and pass one of the following flags
--added--changed--deprecated--fixed--removed--security
You can run changelog insert --help to see a complete list of the supported change types, including their shortcuts and aliases.
Releasing
Up until now, all our changes are documented under the [Unreleased] section.
Now we are going to change that.
First, we check what’s contained in our next release.
$ changelog show next
## [Unreleased] ### Added • A shiny new feature ### Removed • A boring old feature Just as we expect, it only consists of our two changes. To be fair, this command is much more helpful when you have a long list of historic releases that you don’t want to look at every time.
Now we choose, whether we want to increment the major, minor, or patch version and run the release command.
$ changelog release --minor
## [0.1.0] - 2024-03-05 ### Added • A shiny new feature ### Removed • A boring old feature # 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.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]## [0.1.0] - 2024-03-05
### Added
- A shiny new feature
### Removed
- A boring old featureWe chose to explicitly pass the --minor flag here, but you can also pass no flag to the release command to interactively choose the next version.
Closing Notes
And now we are done!
The steps in the example are roughly the workflows that motivated the creation of Keepac.
I grew tired of looking up the exact headings that Keep a Changelog uses, inserting them manually, or manually looking up todays date for a release.
Every one of these steps does not sound that inconvenient, but I found implementing them using changelog much more convenient!
There is more to explore.
You can run changelog --help to explore everything.
Here are some examples:
- generate the text for a GitHub release using
changelog show --plain $VERSION(example from Keepacs own release workflow) - open up
CHANGELOG.mdfrom anywhere in your project usingchangelog edit - view the changes of multiple releases combined using
changelog diff --merged 0.2.0 0.2.8 - search for strings in changelogs (like
grep) and see the resulting within context (version, changetype, unlikegrep)
If you want to try it out and you run Linux or MacOS, just run
brew install niclasvaneyk/keepac/keepacTo learn more, such as how to compile it from scratch for Windows support, is visit the project on GitHub.