README.md

Kiwiproject Changelog Generator

Generates changelogs between two versions on GitHub.

Installation

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.

Install directly from GitHub using curl

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

Execute the installation script locally

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.

Building and running the shaded JAR

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

How it works

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.

How to prevent duplicates in change logs

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.

Command line arguments

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.

Default category

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.

Emoji support

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.

External configuration

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):

1. current directory
2. parent directory
3. user's home directory

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! 🤪