Using github_changelog_generator Edit

Published on Jan 13, 2017 by rnelson0.

With the upgrade to Puppet 4 in all of our modules, we have also added the gem github_changelog_generator. This is an automated tool to generate a CHANGELOG.md based on the Issues and PRs from a github repo with minimal manual intervention. No more forgetting about an important change or describing it wrong, the gem handles that for you.

The changelog contents are based on a few things:

  • The current version of the Puppet module per metadata.json. This means updating the metadata.json prior to creating the changelog (i.e. not the X.Y.Z-rc0 versions)
  • All Issues/PRs between every release tag, as well as the last release tag and the present
  • Descriptions are based on the Issue/PR title
  • Issues/PRs are excluded if they have have certain tags. The current list is duplicate, question, invalid, wontfix, modulesync

The Rakefile automatically detects the current version and excludes labels for you. Your manual effort will be to ensure all Issues/PRs are labeled properly, especially those you wish to exclude, and that their titles reflect the contents. We request that you add BREAKING to the title of any backwards-incompatible PRs so users may more easily determine which of the changes in a major version increase are the ones that caused the increase, and to help ensure you do not include a breaking change in a minor or patch release.

To see how this works, let’s look at puppet/r10k’s CHANGELOG.md over time:

  • pre-4.0.0: This is the final hand-crafted Changelog. It looks good, but someone had to add each entry and you can see that the format of each line is different. Most list the number of the change, but not all. Some list the contributor’s name, others list the github account name, and others don’t list anything. It’s difficult to tell which are backward incompatible. The combination of the organic growth of the changelog and Vox Pupuli’s requirements for automated release, there’s a header on top with the current release number and date, but no other release has that information. Well, it’s there, but this was a conversion from a text file to markdown so it doesn’t display properly. This isn’t great.
  • 4.0.0: Now we see the actual release version. The text labels were converted to markdown so we can see each release. Most release headers are missing the date and contain varying amounts of info. It’s otherwise the same when it comes to the change content.
  • 4.0.2: After three releases the changelog looks a little better, but only because we have to scroll further to see the older releases that are missing dates and other details. We are gaining consistency but are still lacking accuracy.
  • 4.1.0: First changelog generated by tooling. No matter how far back we scroll, we see release numbers, dates, and links to the release tags. Underneath each release header is a link to the full diff between the tags, followed by the list of closed issues and merged PRs, if any, and a link to each and the author of PRs. Each entry’s description matches the title. This has consistency AND accuracy!

To generate a changelog for a Vox Pupuli module, first you need an API token. Follow these directions to generate a token and add it to your profile or environment. With the token in place, all you need to do is run a single command at the top level of the repo:

bundle exec rake changelog

That’s it! After generating your changelog, review it (I advise committing your change and viewing it in your branch on GitHub), and make sure it looks okay. Update the title or label on Issues and PRs and generate the changelog again. Review and tweak as necessary until the changelog is accurate and the noise is removed. Commit again and attach it to your release PR.

You can also use the github_changelog_generator gem on your own modules. Add these edits to your Gemfile and Rakefile (requires puppet-blacksmith which should be in your Gemfile and Rakefile already) and you will have the rake target changelog as well!