Changie - Automated Changelog Generation for Large Projects

Preleases

When working on large projects or projects that require a few extra checks before being considered stable it is common to have prerelease builds. They go by many names but most importantly they use semver's prerelease field to define them.

It is still important to share notes on the differences in each prerelease build to communicate what has changed but what do you do when the time comes for the final release?

A common method for this is to create prerelease notes for each build as they are made. Then, when the final version is ready, package all the prerelease changes into one final release. This is because the prerelease builds were really only for testing and once the final version is ready we just want to document what is in the new version.

Changie supports this workflow by moving change fragments to a separate directory when batching new versions. And then when the final version is ready, including that separate directory or directories.

Here is an example workflow. Lets say your project is preparing for a big upgrade in v1.5.0. This release brings a lot of nice features while maintaining backwards compatibility so you want to release a series of release candidates before the final one.

# add features for next releasechangie new# batch our features for this release candidatechangie batch minor --prerelease rc1 --move-dir v1.5# optionally merge to your CHANGELOG.md if desiredchangie merge# repeat the above for as many candidates as your project needs# then when the final is readychangie batch minor --include v1.5 --remove-prereleases# include remove-prereleases to remove the v1.5.0-rcX versions already releasedchangie merge

Options are available if you choose to keep prereleases around, move each prerelease into a new directory each or if you prefer to just chain releases you can use --keep with each build.

Changie batch docs will have all the information you need.

Metadata

In addition to prereleases semver supports build metadata to be included with your versions. This can be used for pretty much anything but a few examples are; operating system, date, time, git hash or any combination.

You can easily include build metadata by adding -m or --metadata to batch.

A small example would be to include the current date and time as well as the first 12 characters of the git hash with each release.

$ changie next minor \    -m $(date +%Y%m%d) \    -m $(git rev-parse --short=12 HEAD)v1.7.0+20220326.4f48261c620e

Changie next will just output what the next version would be, it takes similar parameters as batch.

That is all for now. Reach me on twitter @miniScruffDev or by starting a discussion on GitHub.