Generates changelogs between two versions on GitHub.
You can install using an installation script or by manually building the JAR. The following sections describe these options.
For both installation types, the script assumes that Maven is available since it is required to build the JAR file.
This is the easiest way to install, but of course you should verify that the script is not malicious first. 🤣
To install using the default directory (~/kiwiproject-changelog-script
) and script name (.generate-kiwi-changelog
):
curl -s https://raw.githubusercontent.com/kiwiproject/kiwiproject-changelog/main/etc/install/install.sh | bash
Or, to install to a custom directory and/or with a custom script name:
curl -s https://raw.githubusercontent.com/kiwiproject/kiwiproject-changelog/main/etc/install/install.sh | bash -s -- -d <dir> -n <script-name>
Commands that require user confirmation (such as when uninstalling or if you attempt to update an existing installation)
work using a curl
-based installation, but you must use the -y
(yes) option to avoid interactive prompts and
auto-confirm.
To uninstall, you can:
curl -s https://raw.githubusercontent.com/kiwiproject/kiwiproject-changelog/main/etc/install/install.sh | bash -s -- -u -y
To install the latest version and overwrite an existing installation, run the original curl command again with -y
:
curl -s https://raw.githubusercontent.com/kiwiproject/kiwiproject-changelog/main/etc/install/install.sh | bash -s -- -y
Clone the repository, then navigate to the folder where you cloned it.
From the project root directory, you can install using the default location and script name by doing:
./etc/install/install.sh
This will create a directory ~/kiwiproject-changelog-script
with a script named .generate-kiwi-changelog
inside.
There is also a README.txt
and the JAR file which is executed by the script.
You can also run install.sh
with -h
to get the command line options.
If you want to install to a custom location and/or change the script name, you can do something like:
./etc/install/install.sh -d /data/tools/kiwi-changelog -n gkc
This will install in the /data/tools/kiwi-changelog
directory, creating it is necessary, and the script is named gkc
.
You can also uninstall using the -u
flag. You will be prompted for confirmation, which lets you review the script directory and name are correct.
If you prefer a manual installation, first clone the repository.
To run the changelog generator from the command line, you need to build the shaded JAR which includes all dependencies.
The default Maven build does not include dependencies, so you need to run the build using the shaded-jar
profile:
$ mvn package -DskipTests -Pshaded-jar
This will build the current SNAPSHOT build in the POM. If you want to build a specific version, maybe the latest production release, check out the corresponding release tag and build the JAR:
$ git checkout <release-tag>
$ mvn package -DskipTests -Pshaded-jar
where release-tag
is a valid tag, e.g., v0.6.0
. You can also build from the latest commit, i.e. HEAD
.
If you built from a tag, make sure to check out the main branch once you've built the JAR, and it's a good idea to move
the JAR somewhere else so that it doesn't get deleted the next time a mvn clean
happens.
Now you can run the JAR file with no arguments (or -h
/ --help
) to get usage information, for example:
$ java -jar <path-to-jar>/changelog-generator-0.6.0.jar --help
Changelogs are generated by finding issues and pull requests that are linked to a specific milestone.
The milestone is derived from the revision (tag), which by default is expected to begin with "v"
.
For example, revision v1.4.2
corresponds to milestone 1.4.2
in the GitHub repository.
Revisions can also include pre-release or build metadata, for example v1.0.0-alpha.1
corresponds
to milestone 1.0.0-alpha.1
.
If the repository uses a different tag format, you need to specify the milestone explicitly.
For example, if tags use a format like rel-1.4.2
then you can still generate the changelog
as long as you specify the milestone.
Both the revision and the previous revision must be specified. The reason is so the changelog generator can find the unique commit authors between these two revisions, and list them as contributors to the release. Note specifically that the contributors are the people who created the commits, not the people who created the issue or merged the pull request. Note also that issues and pull requests do not include any information about commits related to them, so the author information can only be obtained from the commits that occurred during the milestone.
Labels on the issues and pull requests are mapped to a category. For example, the label "enhancement" might map to the category "Improvements." And you can also specify an emoji for each category for a nicer-looking changelog.
Because change logs are generated from the issues and pull requests associated with a milestone, the resulting change log will contain duplicates if an issue and its associated pull request are both linked to the milestone.
To prevent this, link either the issue to a milestone (this is our preference for our own repositories), or link the pull request, but not both.
Issues which do not have an associated pull request (was that you who force-pushed 🔥 it straight to main?) should be linked to a milestone so that they are included in the change log.
Similarly, pull requests that are not associated with an issue, such as ones created by dependabot, should be linked to a milestone so that they are included in the change log.
Here is a sample argument list that generates a changelog for the kiwi
project (inside the kiwiproject organization on GitHub) for version 2.5.0.
It creates the changelog comparing from revision v2.4.0 to v2.5.0.
It also maps several labels to categories, e.g., -m bug:Bugs
maps from the GitHub label bugs
to the
changelog category "Bugs" (you can also use --mapping
). The -O
option (you can also use --category-order
)
specifies the order of the categories in the generated changelog.
--repo-host-token [YOUR_GITHUB_ACCESS_TOKEN]
--repository kiwiproject/kiwi
--previous-rev v2.4.0
--revision v2.5.0
-m bug:Bugs
-m "new feature:Improvements"
-m enhancement:Improvements
-m "dependencies:Dependency Updates"
-m "code cleanup:Assorted"
-m refactoring:Assorted
-O Improvements
-O Bugs
-O Assorted
-O "Dependency Updates"
In the -m
options, the GitHub label comes first, then a colon, and finally the category name.
When a label or category name contains a space, you'll need to enclose the entire argument in
quotes.
Make sure to use the exact same category name in the -m
and -O
arguments.
The changelog produced using the above arguments is here.
Note that you need a GitHub personal access token
that has appropriate access to be able to read issues in the repository.
You can supply this token using the command line (as shown above), or by setting an environment variable
named KIWI_CHANGELOG_TOKEN
.
If you don't specify (or don't want to specify) a mapping for every label, then a default category is assigned. The default category is Assorted with no emoji.
You can specify the default category using the --default-category
(or -c
) command
line argument.
You can also add some 🌶️ to your change logs using emoji.
Use the -e
or --emoji-mapping
command line options to specify the emoji to use for a category.
For example:
-m "bug:Bugs"
-m "new feature:Improvements"
-m enhancement:Improvements
-m "dependencies:Dependency Updates"
-m "code cleanup:Assorted"
-m refactoring:Assorted
-e "Bugs:🐛"
-e "Improvements:🚀"
-e "Dependency Updates:⬆️"
-e "Assorted:👜"
-O Improvements
-O Bugs
-O Assorted
-O "Dependency Updates"
Make sure to use the same exact category names in the -m
, -e
, and -O
options.
As of version 0.6.0, you can create a .kiwi-changelog.yml
. Here is a sample configuration
that is equivalent to the above command line arguments:
---
categories:
- name: Improvements
emoji: 🚀
labels:
- new feature
- enhancement
- name: Bugs
emoji: 🐛
labels:
- bug
- name: Assorted
emoji: 👜
default: true
labels:
- code cleanup
- refactoring
- name: Dependency Updates
emoji: ⬆️
labels:
- dependencies
Here is another sample changelog configuration. This is the one we are currently for kiwiproject releases.
Using a configuration file is more convenient when you have a common set of categories. Note that
the default category is specified using the default
property in one of the categories.
If you specify more than one default category, then the first one is used.
The .kiwi-changelog.yml
file is searched for in the following order (relative to the directory
where the changelog generator JAR is executed):
This order lets you have a custom changelog configuration for a repository, or a group of repositories such as an organization, or a configuration to be used for any repository.
If you don't want any .kiwi-changelog.yml
configuration files to be used at all, you can
use the --ignore-config-files
(or -g
) command line flag.
You can also override the above and specify a custom configuration file using the
--config-file
(or -n
) command line option, e.g. --config-file /path/to/custom/changelog.yml
.
If you export KIWI_CHANGELOG_TOKEN
to your environment, and you use a configuration file, then
generating change logs can be as simple as:
.generate-kiwi-changelog --repository kiwiproject/kiwiproject-changelog \
--previous-rev v0.11.0 \
--revision v0.12.0 \
--output-type GITHUB \
--close-milestone \
--create-next-milestone 0.13.0
This generates the change log for the kiwiproject-changelog
repository for milestone 0.12.0
.
It posts the change log to GitHub, closes the 0.12.0
milestone, and creates the next milestone, 0.13.0
.
Using short argument names, it can be even shorter:
.generate-kiwi-changelog -r kiwiproject/kiwiproject-changelog -p v0.11.0 -R v0.12.0 -o GITHUB -C -N 0.13.0
Happy change log generating! 🤪