Changelog generator based on GitHub Pull Requests
The main features:
- Writes in a
CHANGELOG.md
from merged GitHub pull requests since the last tag. This works by- first getting a list of all tags
- than removing all tags that are not compatible to semver versioning
- sort the tags
- getting the git log from the last tag until now
- If no
CHANGELOG.md
existed, it will create the file else it will write prepending to it
- Friendly CLI
- Get usage by running
pr-log --help
- Error messages that help correcting usage mistakes. E.g.
- Missing first command line argument:
Error: version-number not specified
- Local branch is outdated compared to the remote branch:
Error: Local git master branch is 0 commits ahead and 2 commits behind of origin/master
- The current working directory is not clean (e.g. contains files that are modified):
Error: Local copy is not clean
- Missing first command line argument:
- Get usage by running
- Well tested
Simply run this to install pr-log
:
npm install pr-log
You have to follow these steps to use pr-log
without problems.
The following categories are defined by default:
GitHub label | Human friendly name | Description |
---|---|---|
breaking |
Breaking Changes | Backwards-incompatible changes |
bug |
Bug Fixes | Changes that only fix a bug |
feature |
Features | New features |
enhancement |
Enhancements | Non-breaking improvements of existing features |
documentation |
Documentation | Changes to documentation and/or README |
upgrade |
Dependency Upgrades | Any kind of dependency updates |
refactor |
Code Refactoring | Changes that don’t affect the behavior but improve the code quality |
build |
Build-Related | Changes related to the build process and/or CI/CD pipeline |
However, you can also create a custom mapping by adding a pr-log.validLabels
section to your package.json
.
validLabels
must be specified as an array of key, value pairs. The same order will be used to format the changelog sections.
For example:
{
"pr-log": {
"validLabels": [
["core", "Core features"],
["addon", "Addons"]
]
}
}
To use pr-log
your GitHub project needs some small configuration:
- Create the labels mentioned above (you can create GitHub labels from
Issues -> Labels -> New Label
) - Set the correct label on your pull requests - you need to set exactly one label, multiple labels or one that is not recognized will throw an error
- Use correct semver versioning for your tags (e.g.
2.4.7
)
As pr-log
reads repository information from your project you have to add the repository
information in your package.json
{
"repository": {
"type": "git",
"url": "https://github.com/<your username>/<your repository name>.git"
}
}
If you want to use a custom date format you can configure pr-log.dateFormat
in your package.json
. For example:
{
"pr-log": { "dateFormat": "dd.MM.yyyy" }
}
Please refer to the dates-fn
documentation for details about the format expressions.
To create or update your changelog run
pr-log [options] <version-number>
where version-number
is the name of this release
Example:
Given the following setup:
- In GitHub a tag named
2.0.0
exists that is behindmaster
- A pull request (#13) was created since the last tag that has the label
breaking
- A pull request (#22) was created since the last tag that has the label
documentation
pr-log 2.0.0
creates a changelog with the following example content:
## 2.0.0 (January 20, 2015)
### Breaking Changes
- Use new (backwards incompatible) version of module XYZ (#13)
### Documentation
- Fix some spelling mistakes in documentation. (#22)
The --sloppy
option defaults to false. When set, it allows pr-log
to generate a changelog even when you are not on the master
branch. This should not be used in production!
When enabled this option outputs the stacktrace of an error additionally to the error message to stderr
.
If you want your changelog to be complete and clean you have to follow these rules:
- Don't commit directly to master - if you do, your changes will not be covered in the changelog (this might be ok but you should know this implication)
- Use pull requests for your features that you want to be in your changelog
- Use the correct categories for your pull request: If you introduce a new feature that will be a breaking change, give it the according label
breaking
(which will later result in this feature being listed under theBreaking Changes
point in your changelog)
If you need to authenticate pr-log
, e.g. to access a private repo, you can set the GH_TOKEN
environment variable. Generate a token value in your Github settings.
GH_TOKEN=xxxxxxxxx pr-log [options] <version-number>
Many projects have problems with their changelogs. Most of them try one of the following ways
- manually write change logs: This is error-prone and the log will not be consistent
- generating it from commit messages: As there are often far more commits than useful messages for the changelog, this will hide important features because there are too many to read everything
Other challenges for good changelogs:
- Different categories (e.g. breaking changes)
- Only include changes starting from a certain tag
After working for some time with the tool and having e.g. two releases, the file content could look like this:
## 2.0.0 (January 20, 2015)
### Breaking Changes
- Use new (backwards incompatible) version of module XYZ (#13)
### Features
- Add fancy feature (#2)
-
### Documentation
- Fix some spelling mistakes in documentation. (#22)
## 1.1.0 (November 3, 2014)