What is gbch?
gbch is a tool for generating changelogs from the Backlog Git repository.
It helps collect merge commits via pull requests from the commit log of Backlog’s Git repository and automatically generates a changelog.
gbch is developed by Nulab software engineer, Watanabe, who wrote the information below for the Backlog blog post.
Overview of gbch
- gbch supports Semver (Semantic Versioning) tags, and optionally, you can change the tag prefix to any character.
- It supports output in both Markdown notation and Backlog notation.
- Optionally, you can output the unique ID of the user who is linked to the Nulab account.
- gbch is forked from ghch (github.com/Songmu/ghch), a tool for generating changelogs in the GitHub repository, and modified according to Backlog specifications. (Gbch changelog is generated by ghch)
Example of markdown text output from gbch:
Markdown text output when added to Backlog Git
How to install gbch
Using 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
Using Go:
If you have Go (go 1.14+) installed, you can also install it with go get.
Using 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
Using 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 added to your PATH.
Requirements
Because gbch uses Git commands, you need Git 1.8.5 or higher installed on your machine.
Basic usage of gbch
gbch -r /path/to/repo [–format markdown]
| Options | Explanation |
|---|---|
-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 - Environment variable
BACKLOG_API_KEY
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
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.
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 their ideas.
Thank you very much,
Watanabe.