<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<link href='https://fonts.googleapis.com/css?family=Chivo:900' rel='stylesheet' type='text/css'>
<link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen">
<link rel="stylesheet" type="text/css" href="stylesheets/pygment_trac.css" media="screen">
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print">
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<title>Github-changelog-generator by skywinder</title>
</head>
<body>
<div id="container">
<div class="inner">
<header>
<h1>Github-changelog-generator</h1>
<h2>Automatically generate changelog from your tags, closed issues and merged pull requests.</h2>
</header>
<section id="downloads" class="clearfix">
<a href="https://github.com/skywinder/github-changelog-generator/zipball/master" id="download-zip" class="button"><span>Download .zip</span></a>
<a href="https://github.com/skywinder/github-changelog-generator/tarball/master" id="download-tar-gz" class="button"><span>Download .tar.gz</span></a>
<a href="https://github.com/skywinder/github-changelog-generator" id="view-on-github" class="button"><span>View on GitHub</span></a>
</section>
<hr>
<section id="main_content">
<p><a href="http://badge.fury.io/rb/github_changelog_generator"><img src="https://badge.fury.io/rb/github_changelog_generator.svg" alt="Gem Version"></a>
<a href="https://travis-ci.org/skywinder/Github-Changelog-Generator"><img src="https://travis-ci.org/skywinder/Github-Changelog-Generator.svg?branch=master" alt="Build Status"></a></p>
<h1>
<a id="github-changelog-generator" class="anchor" href="#github-changelog-generator" aria-hidden="true"><span class="octicon octicon-link"></span></a>GitHub Changelog Generator</h1>
<ul>
<li><a href="#installation">Installation</a></li>
<li><a href="#output-example">Output example</a></li>
<li>
<a href="#usage">Usage</a>
<ul>
<li><a href="#params">Params</a></li>
<li><a href="#github-token">GitHub token</a></li>
</ul>
</li>
<li>
<a href="#features-and-advantages-of-this-project">Features and advantages of this project</a>
<ul>
<li><a href="#alternatives">Alternatives</a></li>
<li><a href="#projects-using-this-library">Projects using this library</a></li>
</ul>
</li>
<li><a href="#am-i-missed-some-essential-feature">Am I missed some essential feature?</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
</ul>
<h3>
<a id="changelog-generation-has-never-been-so-easy" class="anchor" href="#changelog-generation-has-never-been-so-easy" aria-hidden="true"><span class="octicon octicon-link"></span></a>Changelog generation has never been so easy:</h3>
<p><strong>Fully automate changelog generation</strong> - This gem generate change log file based on <strong>tags</strong>, <strong>issues</strong> and merged <strong>pull requests</strong> (and split them to separate lists according labels) from <img class="emoji" title=":octocat:" alt=":octocat:" src="https://assets-cdn.github.com/images/icons/emoji/octocat.png" height="20" width="20" align="absmiddle"> GitHub Issue Tracker.</p>
<p>Since now you don't have to fill your <code>CHANGELOG.md</code> manually: just run script, relax and take a cup of <img class="emoji" title=":coffee:" alt=":coffee:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/2615.png" height="20" width="20" align="absmiddle"> before your next release! <img class="emoji" title=":tada:" alt=":tada:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f389.png" height="20" width="20" align="absmiddle"></p>
<blockquote>
<h3>
<a id="whats-the-point-of-a-change-log" class="anchor" href="#whats-the-point-of-a-change-log" aria-hidden="true"><span class="octicon octicon-link"></span></a><em>What’s the point of a change log?</em>
</h3>
<p>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.</p>
<h3>
<a id="why-should-i-care" class="anchor" href="#why-should-i-care" aria-hidden="true"><span class="octicon octicon-link"></span></a><em>Why should I care?</em>
</h3>
<p>Because software tools are for people. If you don’t care, why are you contributing to open source? Surely, there must be a kernel (ha!) of care somewhere in that lovely little brain of yours.</p>
<p><img class="emoji" title=":copyright:" alt=":copyright:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/00a9.png" height="20" width="20" align="absmiddle"> <em><a href="http://keepachangelog.com/">http://keepachangelog.com</a></em></p>
</blockquote>
<h2>
<a id="installation" class="anchor" href="#installation" aria-hidden="true"><span class="octicon octicon-link"></span></a>Installation</h2>
<pre><code>[sudo] gem install github_changelog_generator
</code></pre>
<h2>
<a id="output-example" class="anchor" href="#output-example" aria-hidden="true"><span class="octicon octicon-link"></span></a>Output example</h2>
<ul>
<li>Look at <strong><a href="https://github.com/skywinder/Github-Changelog-Generator/blob/master/CHANGELOG.md">CHANGELOG.md</a></strong> for this project</li>
<li>
<p><a href="https://github.com/skywinder/ActionSheetPicker-3.0/blob/master/CHANGELOG.md">ActionSheetPicker-3.0/CHANGELOG.md</a> was generated by command:</p>
<pre><code>github_changelog_generator -u skywinder -p ActionSheetPicker-3.0
</code></pre>
</li>
<li><p>In general it looks like this:</p></li>
</ul>
<blockquote>
<h2>
<a id="125-2015-01-15" class="anchor" href="#125-2015-01-15" aria-hidden="true"><span class="octicon octicon-link"></span></a>
<a href="https://github.com/skywinder/Github-Changelog-Generator/tree/1.2.5">1.2.5</a> (2015-01-15)</h2>
<p><a href="https://github.com/skywinder/Github-Changelog-Generator/compare/1.2.4...1.2.5">Full Changelog</a></p>
<p><strong>Implemented enhancements:</strong></p>
<ul>
<li>Use milestone to specify in which version bug was fixed <a href="https://github.com/skywinder/Github-Changelog-Generator/issues/22">#22</a>
</li>
</ul>
<p><strong>Fixed bugs:</strong></p>
<ul>
<li>Error when trying to generate log for repo without tags <a href="https://github.com/skywinder/Github-Changelog-Generator/issues/32">#32</a>
</li>
</ul>
<p><strong>Merged pull requests:</strong></p>
<ul>
<li><p>PrettyPrint class is included using lowercase 'pp' <a href="https://github.com/skywinder/Github-Changelog-Generator/pull/43">#43</a> (<a href="https://github.com/schwing">schwing</a>)</p></li>
<li><p>support enterprise github via command line options <a href="https://github.com/skywinder/Github-Changelog-Generator/pull/42">#42</a> (<a href="https://github.com/glenlovett">glenlovett</a>)</p></li>
</ul>
</blockquote>
<h2>
<a id="usage" class="anchor" href="#usage" aria-hidden="true"><span class="octicon octicon-link"></span></a>Usage</h2>
<p><strong>It's really simple</strong>: </p>
<ul>
<li>
<p>If your <strong>git remote</strong> <code>origin</code> refer to your GitHub repo, then just go to your project folder and run:</p>
<pre><code>github_changelog_generator
</code></pre>
</li>
<li>
<p>or from anywhere:</p>
<ul>
<li><code>github_changelog_generator -u github_username -p github_project</code></li>
<li><code>github_changelog_generator github_username/github_project</code></li>
</ul>
</li>
</ul>
<p>As output you will get <code>CHANGELOG.md</code> file with pretty <em>Markdown-formatted</em> changelog.</p>
<h3>
<a id="params" class="anchor" href="#params" aria-hidden="true"><span class="octicon octicon-link"></span></a>Params</h3>
<p>Type <code>github_changelog_generator --help</code> for detailed usage.</p>
<pre><code>Usage: changelog_generator [options]
-u, --user [USER] Username of the owner of target GitHub repo
-p, --project [PROJECT] Name of project on GitHub
-t, --token [TOKEN] To make more than 50 requests per hour your GitHub token required. You can generate it here: https://github.com/settings/tokens/new
-f, --date-format [FORMAT] Date format. Default is %d/%m/%y
-o, --output [NAME] Output file. Default is CHANGELOG.md
--[no-]verbose Run verbosely. Default is true
--[no-]issues Include closed issues to changelog. Default is true
--[no-]issues-wo-labels Include closed issues without labels to changelog. Default is true
--[no-]pr-wo-labels Include pull requests without labels to changelog. Default is true
--[no-]pull-requests Include pull-requests to changelog. Default is true
--[no-]filter-by-milestone Use milestone to detect when issue was resolved. Default is true
--[no-]author Add author of pull-request in the end. Default is true
--unreleased-only Generate log from unreleased closed issues only.
--[no-]unreleased Add to log unreleased closed issues. Default is true
--[no-]compare-link Include compare link between older version and newer version. Default is true
--include-labels x,y,z Issues only with that labels will be included to changelog. Default is 'bug,enhancement'
--exclude-labels x,y,z Issues with that labels will be always excluded from changelog. Default is 'duplicate,question,invalid,wontfix'
--github-site [URL] The Enterprise Github site on which your project is hosted.
--github-api [URL] The enterprise endpoint to use for your Github API.
-v, --version Print version number
-h, --help Displays Help
</code></pre>
<h3>
<a id="github-token" class="anchor" href="#github-token" aria-hidden="true"><span class="octicon octicon-link"></span></a>GitHub token</h3>
<p>Since GitHub allow to make only 50 requests without authentication it's recommended to run this script with token (<code>-t, --token</code> option)</p>
<p><strong>You can easily <a href="https://github.com/settings/applications">generate it here</a></strong>.</p>
<p>And:</p>
<ul>
<li>Run with key <code>-t [your-16-digit-token]</code> </li>
<li>
<p>Or set environment variable <code>CHANGELOG_GITHUB_TOKEN</code> and specify there your token. </p>
<p>i.e. add to your <code>~/.bash_profile</code> or <code>~/.zshrc</code> or any other place to load ENV variables string :</p>
<pre><code>export CHANGELOG_GITHUB_TOKEN="your-40-digit-github-token"
</code></pre>
</li>
</ul>
<p>So, if you got error like this:</p>
<blockquote>
<p>! /Library/Ruby/Gems/2.0.0/gems/github_api-0.12.2/lib/github_api/response/raise_error.rb:14:in `on_complete'</p>
</blockquote>
<p>It's time to create this token or wait for 1 hour before GitHub reset the counter for your IP.</p>
<h2>
<a id="features-and-advantages-of-this-project" class="anchor" href="#features-and-advantages-of-this-project" aria-hidden="true"><span class="octicon octicon-link"></span></a>Features and advantages of this project</h2>
<ul>
<li>Generate canonical, neat change log file, followed by <a href="http://keepachangelog.com/">basic change log guidlines</a> <img class="emoji" title=":gem:" alt=":gem:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f48e.png" height="20" width="20" align="absmiddle">
</li>
<li>Possible to generate <strong>Unreleased</strong> changes (closed issues that have not released yet) <img class="emoji" title=":dizzy:" alt=":dizzy:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f4ab.png" height="20" width="20" align="absmiddle">
</li>
<li>
<strong>GitHub Enterprise support</strong> via command line options! <img class="emoji" title=":factory:" alt=":factory:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f3ed.png" height="20" width="20" align="absmiddle">
</li>
<li>Flexible format <strong>customisation</strong>:
<ul>
<li>
<strong>Customize</strong> issues, that <strong>should be added</strong> to changelog <img class="emoji" title=":eight_spoked_asterisk:" alt=":eight_spoked_asterisk:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/2733.png" height="20" width="20" align="absmiddle">
</li>
<li>
<strong>Custom date format</strong> supported <img class="emoji" title=":date:" alt=":date:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f4c5.png" height="20" width="20" align="absmiddle">
</li>
<li>Ability to manually specify in which version issue was fixed (in case, when closed date is not match) by setting <code>milestone</code> of issue the same name as tag of required version <img class="emoji" title=":pushpin:" alt=":pushpin:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f4cc.png" height="20" width="20" align="absmiddle">
</li>
<li>Automatically <strong>exclude specific issues</strong>, not-related to change log (any issue, that has label <code>question</code> <code>duplicate</code> <code>invalid</code> <code>wontfix</code>by default) <img class="emoji" title=":scissors:" alt=":scissors:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/2702.png" height="20" width="20" align="absmiddle">
</li>
</ul>
</li>
<li>
<p><strong>Distinguish</strong> issues <strong>according labels</strong>. <img class="emoji" title=":mag_right:" alt=":mag_right:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f50e.png" height="20" width="20" align="absmiddle"></p>
<ul>
<li>Merged pull requests (all <code>merged</code> pull-requests) <img class="emoji" title=":twisted_rightwards_arrows:" alt=":twisted_rightwards_arrows:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f500.png" height="20" width="20" align="absmiddle">
</li>
<li>Bug fixes (by label <code>bug</code> in issue) <img class="emoji" title=":beetle:" alt=":beetle:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f41e.png" height="20" width="20" align="absmiddle">
</li>
<li>Enhancements (by label <code>enhancement</code> in issue) <img class="emoji" title=":star2:" alt=":star2:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f31f.png" height="20" width="20" align="absmiddle">
</li>
<li> Issues (closed issues <code>w/o any labels</code>) <img class="emoji" title=":non-potable_water:" alt=":non-potable_water:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f6b1.png" height="20" width="20" align="absmiddle"><br>
</li>
</ul>
</li>
<li><p>You manually can set which labels should be included/excluded. <img class="emoji" title=":wrench:" alt=":wrench:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f527.png" height="20" width="20" align="absmiddle"></p></li>
<li>Apply a lot of other customisations, to fit changelog for your personal style <img class="emoji" title=":tophat:" alt=":tophat:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f3a9.png" height="20" width="20" align="absmiddle">
(<em>look <code>github_changelog_generator --help</code> for details)</em>
</li>
</ul>
<h3>
<a id="alternatives" class="anchor" href="#alternatives" aria-hidden="true"><span class="octicon octicon-link"></span></a>Alternatives</h3>
<p>Here is a <a href="https://github.com/skywinder/Github-Changelog-Generator/wiki/Alternatives">wikipage list of alternatives</a>, that I found. But no one was satisfy my requirements.</p>
<p><em>If you know other projects - feel free to edit this Wiki page!</em></p>
<h3>
<a id="projects-using-this-library" class="anchor" href="#projects-using-this-library" aria-hidden="true"><span class="octicon octicon-link"></span></a>Projects using this library</h3>
<p><a href="https://github.com/skywinder/Github-Changelog-Generator/wiki/Projects-using-Github-Changelog-Generator">Wikipage with list of projects</a> </p>
<p><em>If you are using <code>github_changelog_generator</code> for generation change log in your project or know another project that uses it, please add it to <a href="https://github.com/skywinder/Github-Changelog-Generator/wiki/Projects-using-Github-Changelog-Generator">this</a> list.</em></p>
<h2>
<a id="am-i-missed-some-essential-feature" class="anchor" href="#am-i-missed-some-essential-feature" aria-hidden="true"><span class="octicon octicon-link"></span></a>Am I missed some essential feature?</h2>
<ul>
<li><p><strong>Nothing is impossible!</strong> </p></li>
<li><p>Open an <a href="https://github.com/skywinder/Github-Changelog-Generator/issues/new">issue</a> and let's make generator better together! </p></li>
<li><p><em>Bug reports, feature requests, patches, well-wishes are always welcome</em> <img class="emoji" title=":heavy_exclamation_mark:" alt=":heavy_exclamation_mark:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/2757.png" height="20" width="20" align="absmiddle"></p></li>
</ul>
<h2>
<a id="faq" class="anchor" href="#faq" aria-hidden="true"><span class="octicon octicon-link"></span></a>FAQ</h2>
<ul>
<li><strong><em>I already use GitHub Releases. Why do I need this?</em></strong></li>
</ul>
<p>GitHub Releases is a very good thing. And it's very good practice to maintain it (not so much people using it yet)! <img class="emoji" title=":congratulations:" alt=":congratulations:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/3297.png" height="20" width="20" align="absmiddle"> </p>
<p>I'm not try to compare quality of auto-generated and manually generated logs.</p>
<p>The Changelog like this sometimes really helps. For example:</p>
<p>When I found a closed bug - it's very useful to understand, in which release it was fixed. In that case you can easily find this issue by # in <code>CHANGELOG.md</code>.</p>
<ul>
<li>it's not so quite easy to find it in manually filled Releases notes.</li>
<li>this file can also help you to build your Release note and not miss features in manually-filled list.</li>
</ul>
<p>In the end:</p>
<p>I think, that GitHub Releases is more for end-users.
But <code>CHANGELOG.md</code> could stay in the repo for developers with detailed list of changes.
And it's nothing bad to combine GitHub Releases and <code>CHANGELOG.md</code> file together in that manner.</p>
<h2>
<a id="contributing" class="anchor" href="#contributing" aria-hidden="true"><span class="octicon octicon-link"></span></a>Contributing</h2>
<ol>
<li>Create an issue to discuss about your idea</li>
<li><a href="https://github.com/skywinder/Github-Changelog-Generator/fork">Fork it</a></li>
<li>Create your feature branch (<code>git checkout -b my-new-feature</code>)</li>
<li>Commit your changes (<code>git commit -am 'Add some feature'</code>)</li>
<li>Push to the branch (<code>git push origin my-new-feature</code>)</li>
<li>Create a new Pull Request</li>
<li>Profit! <img class="emoji" title=":white_check_mark:" alt=":white_check_mark:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/2705.png" height="20" width="20" align="absmiddle">
</li>
</ol>
<h2>
<a id="license" class="anchor" href="#license" aria-hidden="true"><span class="octicon octicon-link"></span></a>License</h2>
<p>Github Changelog Generator is released under the <a href="http://www.opensource.org/licenses/MIT">MIT License</a>.</p>
</section>
<footer>
Github-changelog-generator is maintained by <a href="https://github.com/skywinder">skywinder</a><br>
This page was generated by <a href="https://pages.github.com">GitHub Pages</a>. Tactile theme by <a href="https://twitter.com/jasonlong">Jason Long</a>.
</footer>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-52127948-2");
pageTracker._trackPageview();
} catch(err) {}
</script>
</div>
</div>
</body>
</html>