This is chalog, a changelog management tool. With chalog you can manage your project's changelog in a simple markdown format, split across multiple files, and then use chalog to generate the final combined changelog.
This is primarily to address the issue of merge conflicts in changelogs, which can occur easily if there are multiple people working on a single project (there have been a few articles with other solutions to this problem, this is just a different solution).
The chalog tool currently only works with the keep a changelog v1.1.0 changelog format, and on releases hosted on GitHub.
The format for chalog is intended to be simple, readable, and not require much knowledge or configuration - chalog works out of the box without any configuration.
The format for storing your changelog is a changelog directory with subdirectories, with each subdirectory being a release in your changelog. Inside these release directories there can be any number of markdown files (no markdown files is still valid) which contain the changes for the release. When the chalog tool is run these files are read and grouped by release, combining them into a single changelog markdown file.
It is important that when you create your markdown files as part of your changelog, they should be split up by
top level headers (e.g. # Added
) because chalog uses these headers to group changes. If no header is provided, the
file will be ignored.
If using a Go development environment, chalog can be installed by running:
go install -ldflags="-X 'main.Version=v1.0.0'" github.com/jthomperoo/chalog@v1.0.0
Otherwise, the packaged binaries can be used, check out the available binaries for v1.0.0
from the GitHub releases
page here.
-
Install chalog.
-
Add a new
.changelog
directory to the root directory of your project. -
Add a new
Unreleased
subdirectory to your new.changelog
directory. -
Add a new
v1.0.0
subdirectory to your new.changelog
directory. -
Create a new markdown file under the
v1.0.0
subdirectory calledinit.md
with the following content:
# Added
- Initial release of my project!
-
Now run
chalog
in the root directory of your project, if it is successful it will generate aCHANGELOG.md
file that will contain your new combined changelog. -
You now have a chalog formatted changelog set up for your project, try adding some more markdown files under releases, or adding new releases and check how the
CHANGELOG.md
file is generated after runningchalog
again.
For an example of a project using chalog, look at the chalog project itself - it uses itself to manage its changelog.
You can see the latest generated changelog attached as an asset to the latest release.
The chalog tool includes some configuration options that can be set by flags provided to the executable. These are all optional.
Usage: chalog [options]
-config string
path to the config file to load (default ".chalog.yml")
-in string
the directory for storing the changelog files (default ".changelog")
-out string
the changelog file to output to (default "CHANGELOG.md")
-preamble string
path to a file containing the preamble to insert at the start of the changelog
-repo string
the repository base url, include the protocol (http/https)
-target string
target to output to, e.g. stdout or a file (default "file")
-unreleased string
the release name that should be treated as a the 'unreleased' section (default "Unreleased")
-version
if the process should be skipped, instead printing the version info
The chalog tool allows you to provide an optional releases.txt
file inside your changelog directory, which allows
you to provide an ordering for the releases in the changelog, and to optionally provide metadata (e.g. the date of a
release). If this file does not exist then the releases will just be sorted according to semantic versioning (as best
as possible) and without any metadata.
To use the releases file, create a releases.txt
in the changelog directory with the following format:
v0.2.0,2021-04-01
v0.1.0,2021-03-07
This will result in a generated changelog which will follow this order, with the dates provided appended as metadata to the release:
## [v0.1.0] - 2021-03-07
If a release is mentioned in the releases file, but there is no directory, the release will be added to the changelog with no changes listed.
The chalog tool allows you to provide an optional YAML configuration, which lets you set any option that is avaialble
as a command line option (other than config
) through a YAML file, which can be easily stored in source control.
The default location of the configuration file is .chalog.yml
in the directory chalog is run in, if there is no
file provided it will ignore it and continue as normal. A path to the configuration file can be provided with the
-config
command line option, e.g. -config my_chalog_config.yml
.
The YAML configuration looks like this:
in: .changelog
out: CHANGELOG.md
unreleased: Unreleased
repo: https://github.com/jthomperoo/chalog
The configuration file is overridden by any command line options provided, so can act as sensible defaults that can be modified by adjusting command line options provided.
Feel free to contribute to this project, here's some useful info for getting set up.
Developing this project requires these dependencies:
Use the following commands to develop:
go run main.go
= run the tool.make lint
= run the code linter against the code, if this does not pass the CI will not pass.make beautify
= run the code beautifier against the code, this must be run for the CI to pass.make test
= run the project tests.make
= cross compile all supported architectures and operating systems.make zip
= zip up all the compiled and built binaries.