Generate Backlog Git changelogs using ‘gbch’
Backlog Staff
November 06, 2020
Introducing gbch, a tool for generating changelogs from the Backlog Git repository.
This article explains our motivation for developing it and how it can be used in your daily work. As a quick side note: While we at Nulab have developed this feature, it is not an official Backlog tool.
Overview of gbch:
- gbch collects merge commits via pull requests from the commit log of Backlog’s Git repository and automatically generates a changelog.
- It is forked from ghch (github.com/Songmu/ghch), a tool for generating changelogs in the GitHub repository, and modified it according to Backlog specifications. (Gbch changelog is generated by ghch)
- gbch supports both Markdown notation and Backlog notation output.
- It supports Semver (Semantic Versioning) tags, and optionally, you can change the tag prefix to any character.
- Optionally, you can output the unique ID of the user who is linked to the Nulab account.
Example of markdown text output from gbch:
Markdown text output when added to Backlog Git
My motivation for developing gbch
Personally, I use ghch to generate git changelogs for the libraries and command-line tools in my Github repository, plus it’s an indispensable tool for release work. In the same vein, I thought that a similar tool could be used to automatically generate Backlog’s Git changelogs, so I decided to try to fork ghch and modify it to fit these specific needs.
How to install gbch
Homebrew
You can install the gbch command in-line tool using Homebrew, a package manager available for MacOS.
| brew tap vvatanabe/gbch brew install gbch |
Go
If you have Go (go1.14+) installed, you can also install it with go get.
| go get github.com/vvatanabe/gbch/cmd/gbch |
GoBinaries
Even if you don’t have Go installed, you can easily install it by making a curl request to gobinaries.com
| curl -sf https://gobinaries.com/vvatanabe/gbch/cmd/gbch | sh |
Github Release Page
You can download the pre-built binaries for each OS from the GitHub release page. After downloading it, place it in a directory that has a path.
Basic usage
Basically, the execution method and options are the same as the original ghch. Here, I will explain the usage according to the README of ghch.
Synopsis
| gbch -r /path/to/repo [–format markdown] |
Options
| -r, –repo= | Target Git repository path (default: .) |
| -g, –git= | Git path (default: git) |
| -f, –from= | For changelog output. Git commit revision range start from. |
| -t, –to= | For changelog output. Git commit revision range end to. |
| –latest | Output only the most recent version of the changelog. |
| –apikey= | To specify the Backlog API key |
| –remote= | Specify the name of the target remote Git repository (default: origin) |
| -F, –format= | Specify the format of the changelog output (value: json, markdown, backlog) |
| -A, –all | All versions |
| -N, –next-version= | Name this version of the changelog (include changes from the last version to the current) |
| -w | Write changelog to file |
| –show-uid | Output includes the unique ID of Nulab account (only for Backlog users that are linked with Nulab account) |
Backlog API key
Backlog API key is required because gbch uses Backlog API v2 internally. The key can be specified with command-line options and environment variables. The command-line option is prioritized over environment variables. How to enter Backlog API key with gbch:
- Command-line option –apikey (note: it’s two dashes ‘-‘)
- Environment variable BACKLOG_API_KEY
Requirements
Because gbch uses Git commands, you need Git 1.8.5 or higher installed on your machine.
Usage Examples
Here are some usage examples, with reference to the original ghch examples.
Display changes between current and last versioned tag in markdown.
| gbch -F=markdown |
Display changes between current and last versioned tag in markdown and name it version v.1.3.0.
| gbch –format=markdown –next-version=v1.3.0 |
Display changes between current and last versioned tag in markdown and write to file CHANGELOG.md.
| gbch -w –format=markdown –next-version=v1.3.0 |
Only display changes in the most recent versioned tag.
| gbch -F markdown –latest |
Display all changes in markdown.
| gbch –format=markdown –next-version=v1.3.0 –all |
Display the changes in the versioned tag range.
| gbch –from v1.2.7 –to v1.3.0 |
Changes made for gbch
Let me take a moment to specify the changes I’ve made for gbch with Backlog Git.
Match Backlog pull request merge commit
The original ghch tool uses regular expressions to determine whether the merge commit is a pull request based on the commit message, but I changed it to match with Backlog’s merge commit.
Getting pull request information using Backlog API
In order to output the changelog from the pull request merge commit, you need the pull request title and author information. gbch uses Backlog API v2 to get that information, thus you need the Backlog API key to run it.
Prefix Semver with any character
The generated changelog is based on Git tags in Semver format, such as v1.0.0 and 1.0.0.
In some cases, when you have multiple sub-projects in a single repository, you might want to give your tags a unique prefix, such as foo-1.0.0, bar-1.0.0, or baz-1.0.0.
By doing this, we have made it possible to specify any character as a prefix so that changelogs can be aggregated for each subproject.
The following is an example of outputting to CHANGELOG_FOO.md by specifying foo- as a prefix.
| gbch -w -F=markdown –ver-prefix=foo- -N foo-1.1.8 CHANGELOG_FOO.md |
Output changelogs in Backlog notation
Backlog supports both markdown and Backlog notation rules for text formatting. (The formatting rules can be accessed under Project Settings by the project administrator.)
To output the changelogs in Backlog notation, you can specify using: gbch -F=backlog
Changelogs in Backlog notation can also be displayed for projects using this rule.
Output the unique ID of the Nulab account associated with the user who created the PR (pull request)
If the user who created the PR has a Nulab account (which some legacy users may not have), you can add the option (–show-uid) to link the unique user ID to the PR and output it.
For example, for a product developed by a team, you may want to share with team members information about the upcoming release changes based on the changelog.
Acknowledgment
Although GitHub and Backlog are different services, gbch was able to utilize almost the same mechanism provided by ghch. We’ve also used gbch in some repositories of Nulab.
Once again: I would like to thank the open-source community and ghch’s author (@songmu) for the opportunity to learn, modify, and build on each other’s ideas.
Thank you very much.
References
