+
GitHub Changelog Generator
-
-
+
- Installation +
- Output example +
-
+Usage
+
+
-
+
- Params +
- GitHub token +
+ - +Features and advantages of this project + + + +
- Am I missed some essential feature? +
- Contributing +
- License +
Changelog generation has never been so easy.
-This script automatically generate change-log from your tags and merged pull-requests.
+Fully automate changelog generation - This gem generate change log file based on tags, issues and merged pull requests from Github issue tracker. This generator complies all change log format guidelines.
-Installation:
+Installation[sudo] gem install github_changelog_generator
+Output example
+ +-
+
- Look at CHANGELOG.md for this project +
-
+
ActionSheetPicker-3.0/CHANGELOG.md was generated by command:
+ +
+github_changelog_generator -u skywinder -p ActionSheetPicker-3.0 +
+ In general it looks like this:
+
+++ +1.2.5 (2015-01-15)
+ + + ++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)
Usage
@@ -52,56 +124,52 @@-
-
+cdto your Project folder with configured git and just type:If your git remote
originrefer to your GitHub repo, then just go to your project folder and run:github_changelog_generator -
-
from anywhere:
+or from anywhere:
-github_changelog_generator -u github-username -p github-project +github_changelog_generator -u github_username -p github_project
As output you will get CHANGELOG.md file with pretty Markdown-formatted changelog.
As output you will get CHANGELOG.md file with pretty Markdown-formatted changelog.
-Params:
++Params
Type github_changelog_generator --help for detailed usage.
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 this script required your OAuth token for GitHub. You can generate it on https://github.com/settings/applications
--h, --help Displays Help
--v, --[no-]verbose Run verbosely. Default is true
- --[no-]issues Include closed issues to changelog. Default is true
- --[no-]issues-without-labels Include closed issues without any labels to changelog. Default is true
- --[no-]pull-requests Include pull-requests to changelog. Default is true
--l, --last-changes Generate log between last 2 tags only
+-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
- --labels x,y,z List of labels. Issues with that labels will be included to changelog. Default is 'bug,enhancement'
+ --[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
-Examples:
- --
-
- Look at changelog for CHANGELOG.md for this project -
-
-
This changelog: ActionSheetPicker-3.0/CHANGELOG.md was generated by command:
- -
-github_changelog_generator -u skywinder -p ActionSheetPicker-3.0 -
-
-FAQ:
++GitHub token
Since GitHub allow to make only 50 requests without authentication it's recommended to run this script with token
@@ -110,11 +178,14 @@And:
-
-
- Run with key
-t [your-16-digit-token]that
+ - Run with key
-t [your-16-digit-token] -
Or set environment variable
-CHANGELOG_GITHUB_TOKENand specify there your token.i.e. add to your
+~/.bash_profileor~/.zshrcor any other place to load ENV variables stringexport CHANGELOG_GITHUB_TOKEN="your-40-digit-github-token"'i.e. add to your
+ +~/.bash_profileor~/.zshrcor any other place to load ENV variables string :export CHANGELOG_GITHUB_TOKEN="your-40-digit-github-token" +
It's time to create this token or wait for 1 hour before GitHub reset the counter for your IP.
++Features and advantages of this project
+ +-
+
- Generate canonical change log file, followed by keepachangelog.com guidlines + +
- Simply add links for all closed issues and merged pull requests +
- Possible to generate Unreleased changes (closed issues that have not released yet) +
- Flexible format customisation:
+
+
-
+
- Customize issues, that should be added to changelog +
- Custom date format supported +
- Ability to manually specify in which version issue was fixed (in case, when closed date is not match) by setting
milestoneof issue the same name as tag of required version
+ - Ability to exclude specific issues from change log (by labels)
+
+
-
+
- Automatically exclude "questions" - issues marked as
questionlabels (and other issues, that shouldn't be in change log file: withduplicate invalid wontfixlabels)
+
+ - Automatically exclude "questions" - issues marked as
+ - Distinguish bug fixes, enchantments, and closed issues according labels.
+
+
-
+
- Issues (closed issues w/o any labels) +
- +Merged pull-requests (all merged pull-requests) +
-
+Bug-fixes (by label
bugin issue)
+ -
+Enhancements (by label
enhancementin issue)
+
+
+Alternatives
+ +Here is a wikipage list of alternatives, that I found. But no one was satisfy my requirements.
+ +If you know other projects - feel free to edit this Wiki page!
+ ++Projects using this library
+ +Wikipage with list of projects
+ +If you are using github_changelog_generator for generation change log in your project or know of project that uses it, please add it to this list.
Am I missed some essential feature?
-Nothing is impossible! Open an issue and let's make generator better together!
+Nothing is impossible!
+ +Open an issue and let's make generator better together!
Bug reports, feature requests, patches, well-wishes are always welcome!
@@ -149,13 +272,14 @@ LicenseGithub Changelog Generator is released under the MIT License.
-