How to Automatically Generate GitHub Release Notes From Resolved Issues

GitHub Issues are convenient since they come bundled with a GitHub repository. Many companies are exploring this tool as an alternative to full-featured issue tracker such as Atlassian JIRA. Complex workflows are not always required, but an issue tracker should be able to answer the question, When a new feature or a bug fix was first shipped? In this article we explore how we solve that problem at Chronicle Software. 

GitHub Releases – How To Make Them Meaningful

GitHub repositories also come with a releases page, which is organized around the concept of git “tags”. Once a git tag is created, an implicit release is created, which may be turned into a fully qualified release by filling in release notes and attaching release artifacts. Frustratingly, GitHub releases do not talk to GitHub issues – an issue has no way of knowing that it was shipped in a release and a release does not know which issues it contains. Being a software company, we had to write some code to fill that feature gap that we are sharing with you.

Figure 1, Shows Release Notes on the GitHub Releases Page

We have contributed an open-source command-line tool, written in Java, which generates release notes for an existing git tag, based on commit messages and turns it into a proper release. Invoke it in a loop, and a short while later all of your tags get a nice release page. It also doubles as a high-level GitHub Release Notes API which can be used to augment release automation code.

Getting Technical About Commits, Issues And Release Notes

GitHub issue references come in three forms: for a current project it’s just a hash sign followed by a number, such as #49. To refer to a different project’s issue, use OrgName/Project#49, and you can also use a full URL such as https://github.com/OpenHFT/OpenHFT/issues/49. Pull Requests also go by the same reference format and may be used in place of issues to simplify workflow.

 

Chronicle Release Notes fetches all GitHub commits between the current and the previous tag, and searches commit messages for issue markers, depending on its settings:

  • It may search for all referenced issues and pull requests, such as “Fix bug (#50)” and “#51 more features added”
  • Or it may only take into account issues but not pull requests, such as “https://github.com/Our/Project/issues/52 new feature implemented”
  • In the most strict mode, only consider issues after “closing keywords”, such as “closes #53”, “resolved #54” or “fix https://github.com/Our/Project/issues/55”
  • Simple issue references and full issue URLs are handled, but not references to different project issues in any form.
  • Labels are processed as issue type, such as “bug” or “enhancement”. Labels may be configured to be excluded, such as, by making “refactoring”-labeled issues not appear in release notes.

 

The project contains detailed README and the command-line tool prints usage instructions when run. Below is the sample invocation of Chronicle Release Notes command-line tool:

 

# Build project from source
mvn clean install -Dgithub.token={github-api-token}


# Generate release notes for a single tag
java -jar cli/target/chronicle-release-notes.jar -T {github-api-token} \
  -r OpenHFT/Project-Name release -t project-2.22 -b main -P -N
#         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Chronicle Release Notes tool Fat Jar
# ^^^^^^^^^^^^^^^^^^^^^^^ GitHub project to generate release notes for
#                                 ^^^^^^^^^^^^^^^ Git tag to augment with release notes
#              Git branch that the tag is part of ^^^^^^^
#     Allow Pull Requests to be included in release notes ^^
#  Comment covered GitHub issues to notify about the release ^^

Propagating Release Information To Issues

Also solved is the inverse “Fix Version” problem, namely, which release(s) were first to have this issue closed. We use GitHub issue comments to carry that information and add those comments via GitHub API:

Figure 2, Shows GitHub Issue with Release Comment

 

To post a custom release notification comment, we run some code during our release process, based on Chronicle Release Notes API. As shown above, commenting issues is also supported by the command-line tool.

 this.releaseConnector = ConnectorProviderFactory.getInstance()
       .getReleaseConnectorProvider(ConnectorProviderKeys.GITHUB).get()
       .connect(token).get();

releaseNotes.getIssues().forEach(issue -> {
   String releasePath = releaseResult.getReleaseUrl();
   String comment = String.format("Released in [%s-%s](%s)",
           project.repositoryName(), projectVersion.format(), releasePath);
   releaseConnector.createIssueComment(project.repositoryName(), issue.getNumber(), comment);
});

Conclusion

As the GitHub ecosystem evolves, it may eventually include the described issue-release integration out of the box. Until that happens, the proposed approach and tooling fills the gap and may be used to manage native release workflow of GitHub projects. Full documentation is available via the links in the Resources section below.

Resources

Chronicle Release Notes GitHub project and README

Chronicle Release Notes project Release Notes generated for itself

Ilya Kaznacheev

Ilya Kaznacheev is an experienced Java developer with web application backend and distributed database background. Ilya is an Apache Ignite project management committee member. Today he is a software engineer at Chronicle Software.

Subscribe to Our Newsletter