Generate changelogs from Backlog Git repositories using ‘gbch’

Generate changelogs from Backlog Git repositories using ‘gbch’

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 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 changelogs for Backlog’s Git repository, 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:

  1. Command-line option –apikey (note: it’s two dashes ‘-‘)
  2. 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.

By outputting the unique ID of the Nulab account, if you are using Typetalk, you can @mention the respective members when you share the changelog in Typetalk. This will notify them in the app, and is a convenient way to inform PR authors.

Example: We have a Typetalk bot to post the changelog generated by gbch. It @mentions the authors at the end of each PR in the log.

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

Watanabe Watanabe is a Software Engineer at Nulab, the creators of Backlog, Cacoo, and Typetalk.