⚠️ This project is no longer actively maintained. I have found myself embracing tools like release-drafter to keep release notes updated automatically, rather than relying on a manually edited CHANGELOG.md. If you are interested in taking over chandler development, let me know by opening an issue.
chandler syncs your CHANGELOG entries to GitHub's release notes so you don't have to enter release notes manually. For Ruby projects, you can even add chandler to your gem's Rakefile to make this an automatic part of your release process!
chandler scans your git repository for version tags (e.g.
v1.0.2), parses out the corresponding release notes for those tags from your
CHANGELOG, and uploads those notes to your project's GitHub Releases via the GitHub API.
By default, chandler makes reasonable assumptions about:
These can all be overridden with command line options.
GitHub Releases are a nice UI for browsing the history of your project and downloading snapshots of each version. It is also structured data that can be queried via GitHub's API, making it a available for third-party integrations. For example, Sibbell can automatically send the release notes out to interested parties whenever you publish a new version.
But as a considerate developer, you also want a plain text
CHANGELOG that travels with the code, can be edited collaboratively in pull requests, and so on.
But that means you need two copies of the same release notes! 😵
chandler takes the hassle out of maintaining these two separate formats.
CHANGELOG is the authoritative source, and GitHub Releases are updated with a simple
CHANGELOGmust be in Markdown, with version numbers in the headings (similar to the format advocated by keepachangelog.com)
gem install chandler
In order to access the GitHub API on your behalf, you must provide chandler with your GitHub credentials.
Do this by creating a
~/.netrc file with your GitHub username and password, like this:
machine api.github.com login defunkt password c0d3b4ssssss!
Alternatively, just expose the ENV variable
CHANDLER_GITHUB_API_TOKEN in your CI.
For more security, you can use an OAuth access token in place of your password. Here's how to generate one. Make sure to enable
public_repo scope for the token.
To push all
CHANGELOG entries for all tags to GitHub, just run:
chandler will make educated guesses as to what GitHub repository to use, the location of the
CHANGELOG, and which tags represent releases.
You can preview what will happen without actually making changes, using
chandler push --dry-run
To upload only a specific tag (
v1.0.2, for example):
chandler push v1.0.2
Other command-line options:
--git=/path/to/project/.git– location of the local git repository (defaults to
--github=username/repo– GitHub repository to upload to (if unspecified, chandler will guess based on your git remotes)
--changelog=History.md– location of the CHANGELOG (defaults to
--tag-prefix=myapp-– specify Git version tags are in the format
Chandler supports GitHub Enterprise as well as public GitHub repositories. It will make an educated guess as to where your GitHub Enterprise installation is located based on the
origin git remote. You can also specify your GitHub Enterprise repository using the
--github option like this:
Or like this:
To authenticate, Chandler relies on your
~/.netrc, as explained above. GitHub Enterprise users simply need to replace
api.github.com with the hostname of your GitHub Enterprise installation (
github.mycompany.com in the example above).
If you maintain a Ruby gem and use Bundler's gem tasks (i.e.
rake release) to publish your gem, then you can use chandler to update your GitHub release notes automatically.
require "bundler/gem_tasks" require "chandler/tasks" # Optional: override default chandler configuration Chandler::Tasks.configure do |config| config.changelog_path = "History.md" config.github_repository = "mattbrictson/mygem" end # Add chandler as a prerequisite for `rake release` task "release:rubygem_push" => "chandler:push"
That's it! Now when you run
rake release, your GitHub Release notes will be updated automatically based on your
This project is no longer accepting pull requests. If you are interested in taking over chandler development, let me know by opening an issue.