github-changelog-generator / github-changelog-generator

Automatically generate change log from your tags, issues, labels and pull requests on GitHub.

github-changelog-generator

• Changelog generation has never been so easy
• What’s the point of a changelog?
• Why should I care?
• Installation
• Usage
  • Running with CLI:
  • Running with Docker
• Output example
  • Params
  • Params File
  • GitHub token
• Migrating from a manual changelog
  • Rake task
• Features and advantages of this project
  • Using the summary section feature
  • Alternatives
  • Projects using this library
• Practical Use Cases
  • Creating GitHub Release Notes
• Am I missing some essential feature?
• FAQ
• Contributing
• Contact us
• License

Changelog generation has never been so easy

Fully automated changelog generation - This gem generates a changelog file based on tags, issues and merged pull requests (and splits them into separate lists according to labels) from GitHub.

Since you don't have to fill your CHANGELOG.md manually now: just run the script, relax and take a cup of ☕ before your next release! 🎉

What’s the point of a changelog?

To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Why should I care?

Because software tools are for people. "Changelogs make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project."

➡️ https://keepachangelog.com

Installation

GitHub Changelog Generator is a Ruby program, distributed as a RubyGem. The Ruby language homepage has an Installation page.

Install the gem like:

$ gem install github_changelog_generator

Depending on your system, you may need to run the shell as an Administrator (Windows), or use sudo gem install github_changelog_generator (Linux).

Usage

Running with CLI:

   github_changelog_generator -u github_project_namespace -p github_project

(where the project namespace is likely your username if it's a project you own, but it could also be the namespace of the project)

Running with Docker

Using Docker is an alternative to installing Ruby and the gem.

Example invocation:

$ docker run -it --rm -v "$(pwd)":/usr/local/src/your-app githubchangeloggenerator/github-changelog-generator

• For GitHub Enterprise repos, specify both --github-site and --github-api options:

   $ github_changelog_generator --github-site="https://github.yoursite.com" \
                              --github-api="https://github.yoursite.com/api/v3/"
  

This generates a CHANGELOG.md, with pretty Markdown formatting.

Output example

• Look at CHANGELOG.md for this project

• ActionSheetPicker-3.0/CHANGELOG.md was generated by command:

  $ github_changelog_generator -u github-changelog-generator -p ActionSheetPicker-3.0
  

• In general, it looks like this:

1.2.5 (2015-01-15)

Full Changelog

Implemented enhancements:

• Use milestone to specify in which version bug was fixed #22

Fixed bugs:

• Error when trying to generate log for repo without tags #32

Merged pull requests:

• PrettyPrint class is included using lowercase 'pp' #43 (schwing)

• support enterprise github via command line options #42 (glenlovett)

Params

Print help for all command-line options to learn more details:

$ github_changelog_generator --help

For more details about params, read the Wiki page: Advanced changelog generation examples

Params File

In your project root, you can put a params file named .github_changelog_generator to override default params:

Example:

unreleased=false
future-release=5.0.0
since-tag=1.0.0

GitHub token

GitHub only allows 50 unauthenticated requests per hour.

Therefore, it's recommended to run this script with authentication by using a token.

Here's how:

• Generate a token here - you only need "repo" scope for private repositories
• Either:
  • Run the script with --token <your-40-digit-token>; OR
  • Set the CHANGELOG_GITHUB_TOKEN environment variable to your 40 digit token

You can set an environment variable by running the following command at the prompt, or by adding it to your shell profile (e.g., .env, ~/.bash_profile, ~/.zshrc, etc):

export CHANGELOG_GITHUB_TOKEN="«your-40-digit-github-token»"

So, if you get a message like this:

API rate limit exceeded for github_username.
See: https://developer.github.com/v3/#rate-limiting

It's time to create this token! (Or, wait an hour for GitHub to reset your unauthenticated request limit.)

Migrating from a manual changelog

Knowing how dedicated you are to your project, you probably haven't been waiting for github-changelog-generator to keep a changelog. But you probably don't want your project's open issues and PRs for all past features listed in your historic changelog, either.

That's where --base <your-manual-changelog.md> comes in handy! This option lets append your old manual changelog to the end of the generated entries.

If you have a HISTORY.md file in your project, it will automatically be picked as the static historical changelog and appended.

Rake task

You love rake? We do, too! So, we've made it even easier for you: we've provided a rake task library for your changelog generation.

Configure the task in your Rakefile:

require 'github_changelog_generator/task'

GitHubChangelogGenerator::RakeTask.new :changelog do |config|
  config.user = 'username'
  config.project = 'project-name'
  config.since_tag = '0.1.14'
  config.future_release = '0.2.0'
end

All command-line options can be passed to the rake task as config parameters. And since you're naming the rake task yourself, you can create as many as you want.

You can look for params names from the parser source code (#setup_parser). For example, to translate the bugs label to Portuguese, instead of setting config.bugs_label, you have to set config.bug_prefix, and so on.

Features and advantages of this project

• Generate canonical, neat changelog file, with default sections that follow basic changelog guidelines 💎

• Optionally generate Unreleased changes (closed issues that have not released yet) 💫

• GitHub Enterprise support via command line options! 🏭

• Flexible format customization:

  • Customize issues that should be added to changelog ✳️
  • Custom date formats supported (but keep ISO 8601 in mind!) 📅
  • Manually specify the version that fixed an issue (for cases when the issue's Closed date doesn't match) by giving the issue's milestone the same name as the tag of version 📌
  • Automatically exclude specific issues that are irrelevant to your changelog (by default, any issue labeled question, duplicate, invalid, or wontfix) ✂️

• Distinguish issues by labels. 🔎

  • Merged pull requests (all merged pull-requests) 🔀
  • Bug fixes (issues labeled bug) 🪲
  • Enhancements (issues labeled enhancement) 🌟
  • Issues (closed issues with no labels) 🚱
  • Plus any additional custom label-to-section mappings you want ⚙️

• Manually include or exclude issues by labels 🔧

• Customize lots more! Tweak the changelog to fit your preferences 🎩 (See github_changelog_generator --help for details)

Using the summary section feature

For each version, you can add a release summary with text, images, gif animations, etc, and show new features and notes clearly to the user. This is done using GitHub metadata.

Example: adding the release summary for v1.0.0:

1. Create a new GitHub Issue
2. In the Issue's Description field, add your release summary content

![image](https://user-images.githubusercontent.com/12690315/45935880-006a8200-bfeb-11e8-958e-ff742ae66b96.png)

Hello, World! :tada:

3. Set the Issue Label release-summary and add it to the GitHub Milestone v1.0.0
4. Close the Issue and execute github-changelog-generator
5. The result looks like this:

v1.0.0 (2014-11-07)

Full Changelog

Hello, World! 🎉

Implemented enhancements:

• Add some features

Alternatives

Here is a wikipage list of alternatives that I found. But none satisfied my requirements.

If you know other projects, feel free to edit this Wiki page!

Projects using this library

Here's a wikipage list of projects.

If you've used this project in a live app, please let me know! Nothing makes me happier than seeing someone else take my work and go wild with it.

If you are using github_changelog_generator to generate your project's changelog, or know of other projects using it, please add it to this list.

Practical Use Cases

Creating GitHub Release Notes

github_changelog_generator can be used in combination with the github cli to create release notes. Use the --since-tag and --output options of github_changelog_generator to create a changelog for the current release and store the results in a file. In the example below, version 2.0.0 is the current release and version 1.0.0 is the previous release.

mkdir -p build
github_changelog_generator \
  --since-tag 1.0.0 \
  --output build/changelog.md

Then use the release create feature of the github cli to create a new github release

gh release create 2.0.0 \
  --notes-file build/changelog.md \
  --title 2.0.0

Am I missing some essential feature?

• Nothing is impossible!

• Open an issue and let's make the generator better together!

• Bug reports, feature requests, patches, and well-wishes are always welcome. ❗

FAQ

• I already use GitHub Releases. Why do I need this?

GitHub Releases is a very good thing. And it's very good practice to maintain it. (Not a lot of people are using it yet!) ㊗️

BTW: I would like to support GitHub Releases in next releases ;)

I'm not trying to compare the quality of handwritten and auto-generated logs. That said....

An auto-generated changelog really helps, even if you manually fill in the release notes!

• I want to define my own label-to-section mapping, how can I do it?

This is possible using either the add-sections or configure-sections entry in .github_changelog_generator. For example, to add a single new entry called "Maintenance" that will catch PRs tagged with your maintenance label, you can add to .github_changelog_generator the line:

add-sections= {"maintenance":{"prefix":"**Project maintenance**","labels":["maintenance"]}}

A similar approach can be used via configure-sections to set all section properties (including adding new ones!).

• My Ruby version is very old, can I use this?

When your Ruby is old, and you don't want to upgrade, and you want to control which libraries you use, you can use Bundler.

In a Gemfile, perhaps in a non-deployed :development group, add this gem:

group :development do
  gem 'github_changelog_generator', require: false
end

Then you can keep back dependencies like rack, which currently is only compatible with Ruby >= 2.2.2. So, use an older version for your app by adding a line like this to the Gemfile:

gem 'rack', '~> 1.6'

This way, you can keep on using github_changelog_generator, even if you can't get the latest version of Ruby installed.

• Windows: 1.14.x wants to create a file on an invalid path. Why?

Windows: v1.14.0 introduced a bug where it attempts to create /tmp/github_changelog-logger.log... which isn't a valid path on Windows and thus fails

Workaround: Create a C:\tmp.

Contributing

Would you like to contribute to this project? CONTRIBUTING.md has all the details on how to do that.

Contact us

Join the chat at gitter : github-changelog-generator

License

GitHub Changelog Generator is released under the MIT License.

github-changelog-generator's Issues

Markdown formating in the last line wrong

Sometimes user is NULL during merges

Example: when generate changelog for https://github.com/rails/rails
for example issue rails/rails#17385
now there is workaround in #40 - in case that user is null - just put "Null user" plug.
Need to research that case.

Ability to keep manual added changelog information

This is sub-task of #209.
Depends of #212

as @estahn mention in #172 (comment)

It would be great if the generator doesn't replace the entire file but just adds missing versions. We have some manual added information which we don't want to lose when generating the changelog.

Detect username and project form origin

To eliminate requirement always put user and project -> try to detect from remote adress of origin in current repo.

Last tag not appeared in changelog

Last tag not appeared in changelog.

Exclude closed (not merged) PR's from changelog.

As @jspahrsummers mention in Mantle/Mantle#468 (comment)

This is special PR to test it: github-changelog-generator/changelog_test#6

Pull Requests in Wrong Tag

We're using a workflow similar to Gitflow (http://nvie.com/img/[email protected]) which means we've got pull requests that get merged into develop, but sometimes hot fixes get merged into release and put in a tag without merging develop, but currently all the Pull requests that have been merged into develop show up in that version.

Is there any solution for this, or we going to be out of luck?

Pull request with invalid label (#26) in changelog appeared.

This test pull-request should not appear in the changelog

Bugs, that closed simultaneously with push not appeared in correct version.

Example skywinder/ActionSheetPicker-3.0#111 and skywinder/ActionSheetPicker-3.0#112
should be in 1.3.9

Support change log for specific branch

This change log not works well with complicated git repos (like https://github.com/vanilla/vanilla )
So it's need to add ability to specify branch and check, that PR is included in that branch.
More info: vanilla/vanilla#2553

Add # character to encapsulate list.

Example: mattt/FormatterKit changelog:

Merged pull requests:

• #147 Return presentDeicticExpression if past interval is less than least significant unit #148 (krzyzanowskim)

marked as header because of # in the beginning.

Add support for fixed issues and implemented enchanments.

Unreleased issues in separate section

Would love to add a flag that includes a Not Released section at the top which is all of the entries which haven't yet been tagged... not sure how easy/hard this would be, if you can give me some idea I can potentially look at implementing it.

Improve method of detecting owner and repository

replace g remote -vv to git config --get remote.origin.url

Generate change log between 2 specific tags

@jspahrsummers comment:

Is there a way to do this between arbitrary commits? I sometimes create tags before writing the release notes, so it'd be nice to create a changelog for “between tag A and tag B.”

Mantle/Mantle#468 (comment)

Bug with wrong credentials in 1.0.1

can't run script without token

Generate change log since/due specific date

This is sub-task of #209.
The similar to #172, but with dates.
i.e. add options:

--since-date, --due-date

To fetch partial issues. Can help to resolve #71 in future.

Add ability to include commits to changelog by regex pattern

Sometimes I fix some minor things directly in develop branch, without creating separate issue.

It will be very handy to have ability ti highlight it in changelog by matching some user-defined regex pattern in commit message.

Example commits in this repo with prefix "fix:" should be added to a new section Fixed issues:

• 07073ea
• 3e981bb
• 922fa9f

Detailed output

After output

Received all closed pull requests ...

It seem like script is hanging. It's needed to be more verbose.

Add support for forked repo (to extend changelog with parent's changes)

GitHub API rate limit exceed for change log generation in large repos (> 3000 issues)

Since I need to fetch details about each issue separately - and GitHub api has limit to 5000 requests per hour - Need to figure out some thing.
Generate second token as temporary workaround?

Can't install on ubuntu 14.04

I get following error:

ERROR:  Error installing github_changelog_generator:
    ERROR: Failed to build gem native extension.

    /usr/bin/ruby2.2 -r ./siteconf20150306-21079-3x51yd.rb extconf.rb
mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

extconf failed, exit code 1

Use milestone to specify in which version bug was fixed

In case, when bug was closed after release date - there is no option to detect, in which version it was fixed.
One of the option - is use milestone for that.
i.e. first - look at milestone name is the same with tag name - then put this bug in that version. Otherwise work as usual, i,e, use closed date to detect in which version, when bug was fixed.

Parsing of existing Change Log file

This is sub-task of #209.

As @estahn mention:

The CHANGELOG.md needs to be parsed and divided into sections which represent the versions, e.g.

    [{ :version => 'v0.0.1', :content => '...' }, { :version => 'v1.0.0', :content => '...' }, ...]

It's needed to implement:

• --amend #211
• Ability to keep manual added information for older version tags #213

generation failed if github commit api return `404 Not Found`

Here's what I've got when running generator for my private repo:

/Users/nantas/.rvm/gems/ruby-2.1.5/gems/github_api-0.12.3/lib/github_api/response/raise_error.rb:14:in `on_complete': GET https://api.github.com/repos/fireball-x/dev/git/commits/38f8efae9be54183fa08373ed203d7c955917003?access_token=xxx: 404 Not Found (Github::Error::NotFound)

For some reason commit 38f8efae9be54 cannot be found in the commit history, but it's still referenced as the commit that closed an issue.

I'm not sure how important it is to get the commit date as the issue closed date. But if the commit is not found, the generator should just use actual_date of the issue without blocking the whole process. Is that right?

Support for GitHub Enterprise

Currently it is only possible for GitHub.com but it should also be able to use GitHub Enterprise.

Is something like this planned?

Implement ability to retrieve GitHub token from ENV variable (to not put it to script directly)

Crash when try generate log for rails

github_changelog_generator -u rails -p rails

/Users/petrkorolev/.rvm/gems/ruby-2.1.5/gems/github_changelog_generator-1.2.1.1/lib/github_changelog_generator.rb:271:in `block in create_log': undefined method `login' for nil:NilClass (NoMethodError)
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/gems/github_changelog_generator-1.2.1.1/lib/github_changelog_generator.rb:270:in `each'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/gems/github_changelog_generator-1.2.1.1/lib/github_changelog_generator.rb:270:in `create_log'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/gems/github_changelog_generator-1.2.1.1/lib/github_changelog_generator.rb:226:in `generate_log_between_tags'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/gems/github_changelog_generator-1.2.1.1/lib/github_changelog_generator.rb:163:in `block in generate_log_for_all_tags'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/gems/github_changelog_generator-1.2.1.1/lib/github_changelog_generator.rb:162:in `each'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/gems/github_changelog_generator-1.2.1.1/lib/github_changelog_generator.rb:162:in `generate_log_for_all_tags'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/gems/github_changelog_generator-1.2.1.1/lib/github_changelog_generator.rb:135:in `compund_changelog'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/gems/github_changelog_generator-1.2.1.1/bin/github_changelog_generator:4:in `<top (required)>'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/bin/github_changelog_generator:23:in `load'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/bin/github_changelog_generator:23:in `<main>'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/bin/ruby_executable_hooks:15:in `eval'
    from /Users/petrkorolev/.rvm/gems/ruby-2.1.5/bin/ruby_executable_hooks:15:in `<main>'

Add ability to run with one parameter instead -u -p

i.e. to put just skywinder/Github-Changelog-Generator
ot url https://github.com/skywinder/Github-Changelog-Generator as one parameter

Test Question (should not appear in changelog)

This is a test question that shouldn't include in any CHANGELOG.

Error when trying to generate log for repo without tags

Hi There,

I am getting the following error when running the command with my token.

Generating changelog:
Sorting tags..
Generating log..
/Library/Ruby/Gems/2.0.0/gems/github_changelog_generator-1.2.0/lib/github_changelog_generator.rb:326:in `get_time_of_tag': undefined method `[]' for nil:NilClass (NoMethodError)
        from /Library/Ruby/Gems/2.0.0/gems/github_changelog_generator-1.2.0/lib/github_changelog_generator.rb:207:in `generate_log_between_tags'
        from /Library/Ruby/Gems/2.0.0/gems/github_changelog_generator-1.2.0/lib/github_changelog_generator.rb:246:in `generate_log_before_tag'
        from /Library/Ruby/Gems/2.0.0/gems/github_changelog_generator-1.2.0/lib/github_changelog_generator.rb:159:in `generate_log_for_all_tags'
        from /Library/Ruby/Gems/2.0.0/gems/github_changelog_generator-1.2.0/lib/github_changelog_generator.rb:128:in `compund_changelog'
        from /Library/Ruby/Gems/2.0.0/gems/github_changelog_generator-1.2.0/bin/github_changelog_generator:4:in `<top (required)>'
        from /usr/bin/github_changelog_generator:23:in `load'
        from /usr/bin/github_changelog_generator:23:in `<main>'

Would you know what should I do?

Thanks!

Script fills changelog only for first 30 tags.

It's needed to update API according this discussion:
http://stackoverflow.com/questions/26803306/get-all-tags-from-github-repository

Test issue

Test issue to check filters. - any invalid isue should not be included in CHANGELOG

Fetch missing versions and `amend` them to existing change log

This is sub-task of #209.
Depends of #212
Needed to implement partial update of the CHANGELOG.md. i.e. fetch only specific issues (between specific tags, or between time) and not modify others records. i.e. kind of --amend command in git.

This will be a great workaround and fix #71.

Partial updates / add missing versions

It would be great if the generator doesn't replace the entire file but just adds missing versions and ignores existing ones. We have some manual added information which we don't want to lose when generating the changelog.

Features:

• Ability to keep manual added information for older version tags
• Reduced GitHub API calls due to reduce amount of data necessary to retrieve
• Stop/continue a changelog generation process due to partial updates

Implementation:
The CHANGELOG.md needs to be parsed and divided into sections which represent the versions, e.g.

[{ :version => 'v0.0.1', :content => '...' }, { :version => 'v1.0.0', :content => '...' }, ...]

Missing versions can be fetched from the GitHub API and appended.

This might be related to #172.

Detect correct date in case of closing issue by mention in another PR.

Example: skywinder/ActionSheetPicker-3.0/pull/149

Exclude related issues or PR's to avoid redundancy

This topic is described here: nodegit/nodegit/pull/465.

many of those PRs are fixing things introduced in the release, so it seems odd to include them in the changelog.

and:

That would be great, since we could exclude issues fixed that were introduced in the same release

Update URL in project description

https://skywinder.github.io/github-changelog-generator/ is the working link.

Implement option to specify output filename

Example: ... -o my_CHANGELOG.md

Yanked releases support

Following by this changelog conventions - try to figure out, how to support yanked releases.

Separate by lists: Enhancements, Bugs, Pull requests.

Now it's used prefix for each issue, That look god in case 1-2 issues of the same type, but not very nice in case of 5+ same type issues.
It's needed to create at least 3 separate lists per version:

• Merged pull requests:
• Implemented enhancemets:
• Fixed bugs:

Warn users about 0 tags in repo.

To avoid situations like #206

Add ability to specify custom labels for enhancements & bugfixes

To support repositories, that use non-standart labels.

Encapsulate [ > * _ \ ] signs in issues names

Markdown identify > symbol like start quote sign.
It's needed to be encapsulated: />

Separate list exclude and include labels

In order to support more projects with customs labels for bugs etc - better to implement separate list for labels, that included in list and labels, that always excluded.

Do not show `Unreleased` section, when it's empty.

Docs lacking or basic behavior not as advertised

Hi, I came upon this gem and it looks like exactly what I am looking for to generate some changelogs.

Unfortunately I can't get it to work. Ive installed the gem via gem install github_changelog_generator.
When I try github_changelog_generator I receive the following output:

Input options:
{:tag1=>nil,
 :tag2=>nil,
 :format=>"%d/%m/%y",
 :output=>"CHANGELOG.md",
 :labels=>["bug", "enhancement"],
 :pulls=>true,
 :issues=>true,
 :verbose=>true,
 :add_issues_wo_labels=>true,
 :merge_prefix=>"*Merged pull-request:* ",
 :author=>true,
 :pull_request_labels=>["bug", "enhancement"]}

Usage: changelog_generator [options]

Is there additional configuration I need to perform?

Changelog for Private Repository

How I can generate changelog for private repository?
I just generate it and the output only :

Change Log

* This Change Log was automatically generated by github_changelog_generator

Close interaction with "GitHub Releases"

According this news: https://github.com/blog/1547-release-your-software
There is a option to put release notes for each tag in GitHub Releases.
It will be nice to integrate ability to fill this notes by auto-generated change logs
(by using GitHubAPI: releases/edit-a-release )

--no-issues appears to break PRs

When run on the gem release with --no-issues, we only get the header and link to the full changelog