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. Is 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 — and . Together they total more than 1M developers. I’ve recently co-founded a Project Intelligence platform — . Think of it as 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! CodinGame Tech.io Anaxi First, we will 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 , 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 . Linux Foundation label categories What do we call a ? 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. label category 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 corporations? and by Google, by Facebook, by Docker, by RedHat and 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): by CNCF (foundation), and (not backed). Tensorflow AngularJS React Moby Ansible ElasticSearch Kubernetes DefinitelyTyped 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 , , , , 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. experimental discussion technical-debt failing-test docs 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 , , , . 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. active frozen rotten stale 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 Area or Feature, for instance. However, the interesting part is some projects use subcategories, such as … or , or just different label categories but for the same use, like or 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. and area/platform/ area/os/… browser:.. cli:.. 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 . It enables you to be more explicit about the work to be done to move the ticket forward. Typically, is very useful to know, so you can prepare the community or whole team for this change. breaking change, browser fix, docs, feedback, investigation, jquery fix, merging, more info, public api, review, squashing, test, work breaking change Milestone Related: On GitHub, you can add milestones. But some projects add additional label categories related to milestones, such as or . This creates opportunities to discuss and decide. Realistically, part of some weekly meetings could be dedicated to . Ansible also uses labels with an indicator of the versions — etc — that the ticket can affect. This is pretty important when you have clients and customers using previous versions — backward compatibility issues — which is kind of every software unless it is a cloud-hosted SaaS product. milestone/needs-approval, milestone/needs-attention milestone/removed milestone/needs-attention affects_1.2, affects_2.3, 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 and . blocked-paths, hold 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 and 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. documentation refactoring 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. Well, actually, we’re solving this at Anaxi; I’ll come to that later. 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 entreprises 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 they have on this point lately. But we’re still missing quite a lot: progressed 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 I told you there was a tool that would integrate GitHub and let you use your label categories as if they were part of GitHub initially (with pickers)? You could also monitor the issues for each of those labels and get the visibility you were missing. And a lot more is coming. That’s actually what Anaxi does. I hope this article will help you think about your processes and, more precisely, the labels you use. Before you go… Did you find the article interesting? Please holding down the 👏 to say “thanks” and help others find it! If you are interested in articles about , subscribe to our newsletter! engineering and product leadership, productivity and how to scale a team Or join our . Engineering Leadership Community _High-quality trending articles curated by the community on engineering leadership, productivity, how to scale teams and…_community.anaxi.com Engineering Leadership Community | Anaxi You can also check out my latest articles: Originally published at anaxi.com on September 25, 2018.

Facebook

Google

Target

Trello

Velocity

Read My Stories

Too Long; Didn't Read

Developers: Build Less. Deliver More. [Learn how]	

Can Github Be The Most Powerful Ticketing Tool?

Too Long; Didn't Read

Companies Mentioned

John Lafleur

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Can Github Be The Most Powerful Ticketing Tool?

Too Long; Didn't Read

Companies Mentioned

John Lafleur

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES