About the Author

Phillip Verheyden

Software Architect

in Development

Broadleaf Issues - Powered by GitHub

The End of an Era

Since the beginning of Broadleaf we have used Jira for our issue tracking. Some of the cool features that we used and/or liked:

  • Structure around issues
  • Highly advanced search capabilities
  • Out-of-the-box release notes
  • Tracking issues on a sub-issue level
  • Source control integration (via the DVCS Connector)

However, a few months ago we retired our hosted Jira tracker. We have since moved all of our issue tracking to GitHub Issues. This move was prompted for a few reasons:

  1. Using Jira was yet another piece of software that we had to manage and keep track of -- especially since we were hosting it
  2. We only used the issue tracking features. Since we use Trello (and are extremely happy with it) we had no need for Jira's advanced agile features
  3. Ill-defined external code-contribution. Users that wanted to contribute code to the framework via GitHub pull requests (we are open source after all) had to manage it in 2 different spots
  4. Our issues are already very closely tied to the code we write
  5. Most of us at Broadleaf use the GitHub web interface every day
  6. New module extension projects require additional Jira configuration (setup new project, get releasing right, etc)
  7. We wanted to keep our framework activity in one place (issues + code)
  8. We wanted to encourage further public conversation about the code that we were writing for people following the project (with GitHub commit comments)

What About in Practice?

Go and check out our issues on GitHub for yourself! Moving from an advanced system like Jira to a much simpler solution like GitHub issues was a little challenging at first, but we have come up with a few internal processes that have made management much easier.


Most of our issue organization centers around milestones. Milestones correspond to version releases of Broadleaf, with the exception of a few special milestones:

  • Reviewed - Not Yet Assigned - Planning bucket to indicate that someone at Broadleaf has looked at the issue and has validated it as existing but has not prioritized it yet
  • Closed - No Release Required - Bucket for issues that could not be verified or were opened erroneously
  • Feature Requests - Features that have not been tied to a specific release

Tying issues to milestones allows us to easily filter items as they come in (which by default do not have a milestone associated with them) by using the 'Issues with no milestone' filter.

Since milestones are tied to GA releases, this allows users to see all of the issues associated with a Broadleaf release by looking at the closed version milestone, such as the 3.0.1-GA release.

Multiple Milestones - unfortunately GitHub does not allow issues to be assigned multiple milestones. For most projects this is fine; versioning is done in a very linear fashion. However, Broadleaf are in active development of multiple versions at the same time (currently 3.1.0-SNAPSHOT and 3.0.2-SNAPSHOT are in active dev) and release older patch versions with bug fixes. We solved this problem with labels, but we hope that GitHub will eventually allow multiple milestone support.


We still wanted to maintain at least some of the metadata that we were using for our Jira issues. Since we were unable to denote multiple version releases for an issue target we instead use labels (target- labels in the screenshot). We are duplicating other functionality that we had over at Jira with the module- and severity- labels.

Tying Commits to Issues

Since the move to GitHub, we have internally made all of our commits reference GitHub issues. This allows a user to drill down from Broadleaf version release -> high-level issue -> lines of code changed. Then if there's a question about why we changed something or why we've implemented something in a particular way that conversation can happen immediately!

Pull Requests

Since all of our issues are on GitHub, we have a one-stop-shop for directing people to contribute code! Rather than having to communicate back and forth between Jira and GitHub, code contributions and issue comments require a single account and a single location. Plus, since pull requests are really issues at heart it allows external code contributions to naturally flow from issue discussions. Want to open a bug? Why not write some code and submit a pull request?!


Since the move from Jira we haven't looked back. Since we didn't use a lot of the advanced features in the first place, none of us have really missed it. The advantages of having a consistent location to manage all issues, pull request and code across all of our repositories have so far outweighed the big bucket of features that come with using Jira.

Had similar success or in love with Jira? Let us know!