The goal of change
is to take the grunt work out of formatting changelogs. It combines the ideas from
Keep a Changelog
and Conventional Commits
to help you generate and update a changelog template.
This tool cannot not fully write a good changelog for you.
But it can do some of the work!
-
You need to have a least one commit tagged with valid SemVer (like 0.1.0 or v0.0.1).
-
change
probably won't work well with a changelog that's formatted differently. So it's better to letchange
generate one. You can transfer existing messages after.
change
can add multiple versions to your changelog, but those version tags need to already exist. Otherwise, it assumes everything since the last version tag is for the next version.change
will figure out what your next version should be from based on your commits and will add that to the changelog as well.
- You should validate what was generated and add detail everywhere it's needed.
- This looks at the latest version recorded in the changelog. Then it tags the latest commit with that version.
- Optionally, you can provide -p to push the new version:
change tag -p
- This saves a personal access token for posting releases.
- Here are instructions for making one.
- Optionally, you can provide the token non-interactively:
change auth [TOKEN]
- This posts the section of the latest version in the changelog as a GitHub release.
- Optionally, you can provide --dry-run see the url, version, and message body without
creating the release:
change post --dry-run
- First it runs the
change
command. - Then it opens your changelog with $EDITOR (or vi if that isn't set).
- As long as you updated the changelog, it commits and pushes it to origin.
- Lastly, it runs
change tag -p
andchange post
. - I use this command most often.
This is the general workflow I use with this tool:
- make changes to your project
- record those changes in commits
- smaller, more focused commits will help when generating the changelog
- run
change all
- improve the new section of the changelog
- save and close the file
With the help of curl, you can even run this tool without installing it:
curl -s "https://raw.githubusercontent.com/adamtabrams/change/master/change" | sh -s -- [args]
- If you're using
change
like this for CICD, you may want to pick a specific version (instead of master)
If you use change
often, add it to your path. Here are some options for how:
- Create a link to the script in your current path (my favorite):
ln -s /path/to/change/script ~/.local/bin/change
- Add the script's directory to your path:
export PATH="/path/to/change/repo:${PATH};"
- You would probably put this in a file like: .bashrc, .profile, .zprofile, etc
- Copy the script to your current path:
cp /path/to/change/script ~/.local/bin/
- Drawback: the
change
executable will remain at its version when the command was used.