The gulp-github-changelog
package provides a few Gulp tasks for automatic changelog generation in markdown format.
Unlike other similar implementations, this one uses GitHub milestones and issues for its logic.
The !preversion
and !postversion
tasks should be used for the NPM's preversion
and postversion
script hooks.
The !postversion
task publishes the changelog contents in the corresponding GitHub release.
Overview
The generator exposes three gulp tasks - changelog
, !preversion
, and !postversion
.
The changelog
task is meant to be run manually before the release and updates the contents of the CHANGELOG.md
file.
The !preversion
and !postversion
tasks should be attached as script hooks in package.json
, so that the npm version
command will run them automatically.
changelog
For the changelog
task to work as expected, each version should have a matching GitHub milestone in the repository. The milestone name should equal the version name, including "v"
.
For instance, the milestone for version 1.1.0
should be named v1.1.0
. The generator fetches all closed milestone issues and lists them as changes for the respective version.
The issues are grouped in three categories - New
, Enhancements
, and Fixed
. The grouping is based on the standard GitHub tags. Issues with no tag are put in the New
category.
The task will fail if no milestone is found or if the milestone does not have any closed issues.
It also checks if the changelog already contains an entry for that version and aborts the task if so. An optional --force
option may be passed to overwrite the existing entry.
The generated changelog is not automatically committed. This is intentional - the publisher should examine the contents, and, if necessary, add some manual edits in addition to the generated ones.
!preversion
The !preversion
task performs a few sanity checks and aborts the npm version
if something is not right. It will fail when:
- No changelog entry for the new version is present in the
CHANGELOG.md
; The changelog
task should be run first; - Closed issues with no milestone are present. Issues tagged with
duplicate
, invalid
, wontfix
or question
are ignored. The issues are most likely closed without the correct milestone; you should fix this before publishing; - The milestone has any remaining open issues. They should be addressed or moved to the next planned release.
You may put the !preversion
task as a prerequisite to another task which will run the unit tests.
!postversion
The !postversion
task pushes the version tag to GitHub and publishes the changelog piece to the respective release. It also closes the version milestone.
Installation and usage
Install the package as local dev dependency.
npm install --save-dev gulp-github-changelog
Make sure that your package.json
has the correct repository settings (it will be used for the API calls)
"repository": {
"type": "git",
"url": "https://github.com/user/repo.git"
}
Add the preversion
and postversion
script hooks to package.json
:
"scripts": {
"preversion": "gulp '!preversion'",
"postversion": "gulp '!postversion'"
}
Generate a GitHub token for your account, and make it available as an environment variable:
echo 'source $HOME/.github_token' >> .bashrc
echo 'export GITHUB_TOKEN="your token here"' >> $HOME/.github_token
Add the following line to your gulpfile.js
const gulp = require('gulp')
require('gulp-github-changelog')(gulp)
Before your release, run the changelog
task:
gulp changelog -v your_version [--force]
The your_version
parameter accepts the same value as the npm version
command.
If the result does not quite fit the bill, fix the issue titles and categories and re-run the task with the --force
parameter.
Afterwards, run npm version
.