• This repository has been archived on 16/May/2021
  • Stars
    star
    152
  • Rank 244,685 (Top 5 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 9 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

[unmaintained] chandler syncs your CHANGELOG entries to GitHub's release notes

chandler

⚠️ 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.


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!

How does it work?

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:

  • the name of your CHANGELOG file,
  • your project's GitHub repository URL, and
  • the naming convention of your Git version tags.

These can all be overridden with command line options.

Why go through the trouble?

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. Your CHANGELOG is the authoritative source, and GitHub Releases are updated with a simple chandler command.

Requirements

  • Ruby 2.3 or higher
  • Your project's CHANGELOG must be in Markdown, with version numbers in the headings (similar to the format advocated by keepachangelog.com)
  • You must be an owner or collaborator of the GitHub repository to update its Releases

Installation

1. Install the gem

gem install chandler

2. Configure credentials

Option 1 - .netrc

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!

Option 2 - Set ENV variables

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.

Usage

To push all CHANGELOG entries for all tags to GitHub, just run:

chandler push

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 --dry-run:

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 .git)
  • --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 CHANGELOG.md)
  • --tag-prefix=myapp- – specify Git version tags are in the format myapp-1.0.0 instead of 1.0.0

GitHub Enterprise

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:

[email protected]:organization/project.git

Or like this:

--github=https://github.mycompany.com/organization/project

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).

Rakefile integration

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.

1. Update the gemspec

spec.add_development_dependency "chandler"

2. Modify the Rakefile

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 CHANGELOG entries.

And yes, chandler uses itself to automatically push its own release notes to GitHub! Check out the Rakefile.

Contributing

This project is no longer accepting pull requests.

More Repositories

1

rails-template

My former app template for Rails 7. All recommendations you see here have been moved to https://github.com/mattbrictson/nextgen
Ruby
1,084
star
2

airbrussh

Airbrussh pretties up your SSHKit and Capistrano output
Ruby
512
star
3

tomo

A friendly and extensible CLI for deploying Rails apps via SSH
Ruby
379
star
4

bundleup

A friendlier CLI for Bundler’s `update` and `outdated` commands.
Ruby
194
star
5

nextgen

Generate your next Rails app interactively! This template includes production-ready recommendations for testing, security, developer productivity, and modern frontends. Plus optional Vite support! ⚑️
Ruby
132
star
6

capistrano-mb

[unmaintained] Capistrano tasks for deploying Rails from scratch to Ubuntu 16.04 and 18.04
Ruby
119
star
7

bundle_update_interactive

A stylish interactive mode for Bundler, inspired by `yarn upgrade-interactive`
Ruby
101
star
8

rails-starter

I've stopped maintaining this project after reaching Rails 4.1.6. For new versions of Rails, and for my latest Rails configuration suggestions, please use mattbrictson/rails-template.
Ruby
99
star
9

dotfiles

bash, git, rails, Sublime Text 3, homebrew, more...
Ruby
84
star
10

gem

A GitHub template for creating Ruby gems
Ruby
42
star
11

pgcli-rails

Replaces Rails PostgreSQL `dbconsole` with the much nicer `pgcli`
Ruby
33
star
12

minitest-snapshots

Minitest plugin for asserting that strings are the same as a saved snapshot, jest style
Ruby
33
star
13

mighty_test

A modern, TDD-friendly Minitest runner for Ruby projects! Includes a Jest-inspired interactive watch mode, focus mode, CI sharding, fail-fast, and more.
Ruby
6
star
14

jess

Lightweight, unofficial client for the JAMF Software Server (JSS) API
Ruby
5
star
15

tomo-plugin-sidekiq

sidekiq tasks for tomo
Ruby
4
star
16

tomo-plugin

A GitHub template for creating tomo plugins
Ruby
2
star
17

tomo-plugin-nvm

tomo plugin to manage node and yarn via nvm
Ruby
2
star
18

tomo-plugin-rollbar

rollbar tasks for tomo
Ruby
2
star
19

rails-new

Ruby
1
star