How Github Can Be The Most Powerful Ticketing Tool

Compared to all other ticketing tools, GitHub Issues is the only platform giving entire freedom to define whatever types of labels you want. All other tools have an opinion on label types, such as priority, severity, component, epic, etc. Now if you consider that the number of GitHub public active repositories amounts now to 25 million at the end of 2017, and that, well, most of these public (understand open-source) projects are managed through GitHub, then you could be wondering if any best practices have emerged. Are there any unique best practices that cannot be applied to other tools? Should we all switch to GitHub to manage our projects there?

In the past few years, I’ve contributed to the development of two developer platforms – CodinGame and Tech.io. Together they total more than 1 million developers. I’ve recently co-founded another company, Anaxi with the mission of delivering actionable business intelligence for the whole software engineering organization. So, part of my job is identifying growing trends in software development tools. In other words, I think about this kind of thing quite a lot!

First, let’s analyze the 20 most popular open-source projects, how they are structured, and which labels they use.

Then, we will try to find common patterns, to help us understand when and how those best practices can be applied to your project.

Finally, we will compare with other existing project management tools, so you can decide whether GitHub is worth using as your project management tool.

The Top Projects on GitHub

We analyzed the 30 highest-velocity open-source projects on GitHub listed by the Linux Foundation, and selected what we felt were the most well-organized projects. We then analyzed the labels they used to organize their issues, and especially what we call their label categories.

What do we call a label category? Some labels show the following pattern: area/networking, area/hosting, area/backup. “area” is the label category for which there can be lots of labels.

Some projects use “/” to define categories, like in the example above, and others “:”, as Tensorflow and Angular do.

Here is the list of the projects we selected along with the label categories they use:

By the way, did you notice that most projects are backed by big companiescorporations? Tensorflow and AngularJS by Google, React by Facebook, Moby by Docker, Ansible by RedHat and ElasticSearch by Elastic. In the list of 30 that we analyzed, 9 were backed by foundations and only 6 were not backed by an entity. We analyzed them all and kept the best-in-classes in terms of project organization, ending up with one for each (not on purpose): Kubernetes by CNCF (foundation), and DefinitelyTyped (not backed).

Ok, let’s deep dive and see what is interesting about this now.

The Patterns and Best Practices

We identified 7 different types of label categories that those projects were using. If you think it would make more sense to organize the categories differently, don’t hesitate to leave a response – we’re all ears. But here is our take on it.

Type or Kind:

In other project management tools, you would get bug, feature, task or subtask here. But as you can see, GitHub projects are able to expand far beyond this with experimental, discussion, technical-debt, failing-test, docs and much more. That could be interesting to any company. Right now, we generally put everything that is not a bug or feature as a task, but being able to specify what the ticket is should be valuable, whatever the size of your team.

Status/State or Triage/Resolution or Lifecycle:

We grouped these label categories together, as they all inform about the state of the ticket. But each one has nuances. That’s why Kubernetes uses all three – Status, Triage and Lifecycle. Triage and Resolution are used similarly; they explain how the ticket got to this Status/State. While Lifecycle describes the state of the ticket within its state, and has values as active, frozen, rotten, stale. If you have a large number of tickets to handle, this can become very handy, as you can have a process to resurface tickets or just stow them away to enable more focus on what matters.

Priority or Severity or Frequency or Workaround:

We put all four of them together, as they address the same overall issue. But there are important nuances as well. You could actually think that severity, frequency and workaround are 3 different topics that explain the priority better. And a better prioritization can have a massive effect on your business.

Component or Area or Feature:

These are used in a similar way, unlike most of the others. You won’t see a project using Component and Area or Feature, for instance. However, the interesting part is some projects use subcategories, such as area/platform/... or area/os/…, or just different label categories but for the same use, like browser:.. or cli:.. This enables you to have 2 levels of labels to define more precisely which part the code is really about. And within your team, you could have one person responsible for a subcategory, and another for a full category and all its subcategories. So, better delegation and accountability. This is especially helpful to big teams with big projects.

Difficulty or Size or Experience or Need:

This part is about what is required to solve this ticket. It can be time, experience or other dependencies. Other project management tools, like Pivotal Tracker, enable you to put estimates on tickets. The point here is that you can also add information about what level of experience is required for the ticket, which is pretty important for open-source projects. You will want newcomers to start with easy tasks. Angular also uses the label category “needs” with values such as breaking change, browser fix, docs, feedback, investigation, jquery fix, merging, more info, public api, review, squashing, test, work. It enables you to be more explicit about the work to be done to move the ticket forward. Typically, breaking change is very useful to know, so you can prepare the community or whole team for this change.

Milestone Related:

On GitHub, you can add milestones. But some projects add additional label categories related to milestones, such as milestone/needs-approval, milestone/needs-attention or milestone/removed. This creates opportunities to discuss and decide. Realistically, part of some weekly meetings could be dedicated to milestone/needs-attention. Ansible also uses labels with an indicator of the versions – affects_1.2, affects_2.3, etc – that the ticket can affect. This is pretty important when you have clients and customers using previous versions – forward compatibility issues – which is kind of every software unless it is a cloud-hosted SaaS product.

Pull Request Related:

GitHub is first and foremost used for code versioning, and therefore pull requests. Angular typically has the following label categories:

• PR action: cleanup, discuss, merge, merge-assistance, review

• PR state: WIP, blocked

• PR target: master-only, master & patch, patch-only

Kubernetes has do-not-merge/  with values like blocked-paths, hold and work-in-progress.

This enables clarification of the reason for the state of the ticket. My personal feeling is that this doesn’t apply to most non-open-source software projects, though. Feel free to disagree!

So which ticketing tool is best?

First, let’s take note that any additional information you ask your team to provide is an extra effort for them. And if they don’t feel it is worth it, they will naturally not make the effort, and it will just be useless. So, if you’re considering editing your tools and processes, you’d better consider only what is worthwhile for your particular project.

Let’s take 3 different examples to illustrate the point. In no way do I claim that the points below apply to your particular case; only you know what would or would not work for your team.

If you’re a startup with less than 30 engineers

I would think expanding the type of tickets to documentation and refactoring still offers value. Your deployment processes shouldn’t be that complex, so you shouldn’t need any additional label possibilities around status and pull requests. Similarly, milestones shouldn’t hold many intricacies. Having the ability to detail frequency, severity and whether there is a workaround still holds value, but in a startup mode, you would rather maximize the time spent on the output  than on a clean process. Finally, the product shouldn’t be too complex for you to have several layers of components. So overall, the flexibility that GitHub offers is a nice-to-have, but clearly you can have very clean processes without it, by using other tools that offer better user experiences – like Trello, for instance.

If you have several teams working on several products

If you want to have some kind of visibility over all your projects, you’d better be using the same tool in all your teams if you want your team to build consistent reporting on top of it. I would think it is pretty similar to the startup case. It really depends on the team sizes.

If you have large teams working the same products

Typically, this would apply to any complex software, or actually open-source projects. In that case, all the points listed with the label categories apply. And any additional label category could add value. The point is no longer about individual output, but the best communication for the best collective output. That’s actually why a lot of enterprises build their own in-house ticketing tool, with little success. GitHub could be a great solution for them. However, there is a UX and visibility problem with GitHub, but it can be fixed. How? Read on.

But GitHub is missing a lot…?

In terms of project management features, GitHub doesn’t offer the best experience, although it has progressed a lot on this point lately. But we’re still missing quite a lot:

• The interface lets you input labels as text; there is no picker. So you have to know the basic structure of the labels.

• You cannot make any label required when you create an issue

• Labels are great if you want to monitor the tickets assigned with them. You can’t do that on GitHub, unfortunately.

• Visibility over your projects on GitHub is pretty absent, to be honest.

That’s why Jira is the most used tool across the world. You can partially customize your workflow (unfortunately not at the extent of GitHub); it offers a good enough UX to manage tickets on a day-to-day basis and a set of reports so you have some kind of visibility.

What if you could integrate GitHub and use your label categories as if they were part of GitHub initially (with pickers)? Then, you could also monitor the issues for each of those labels and get the visibility you were missing. Better yet, what about integration of GitHub and Jira, so if you are using GitHub for some projects and Jira for others, you could have one single interface for your reporting and get the visibility you need.

I hope this article will help you think about your processes and, more precisely, the labels you use.