5 tips for GitHub Issues & Projects

blog banner image

Being a good developer is not everything. Project management is such an important part of development. You also need a well-structured Backlog, and a good Product Owner, or your projects can flounder and some even fail. At SSW we’ve been using Scrum for many years to manage our projects, and it has hugely reduced the stress and drama that goes along with enterprise software development.

I’ve already talked about the benefits of Scrum, but tools are also important. So, let’s talk about the best ways to manage your GitHub projects, whether you use Scrum or not.

There are lot of great tools out there to do this. In the past we’ve used Jira to manage our projects, and it worked. Then we moved on to TFS, and Azure DevOps which were also great, but now most of our projects are run using GitHub. Whether it be private, or public, it’s a great way to manage your projects.

Here’s a few things that will help keep your projects on track:

#1 Backlog – Keep it lean, keep it clean!

You should have a well organised, pruned Backlog that is nice to look at. With regards to Issue titles, I’ve noticed that a lot of the younger guys particularly like using emojis to help identify an issue quickly. For example, it’s easy to spot a 🐛 to indicate the bugs. There is a lot of debate about this one, but you can see more on SSW Rules | GitHub Repos – Do you write nice commit messages? I think you’ll love the emoji guide for your commit messages. 😜

Good example of nice backlog
Figure: Good Example – A nicely organised and labelled Backlog with emojis that help convey the task

#2 GitHub Issues – Use Templates 

Give good guidance by using templates. GitHub Templates will inform your clients and developers what information you need, before they log an Issue.

No longer will it be difficult to distinguish whether the issue is a bug, feature request or just a question.

You can read more about how to do this here: SSW Rules | GitHub Issues – Do you use Issue Templates?

Good example of GitHub Projects and Issues
Figure: Good example of available Issue Templates, this makes it really easy for people to use your repo. 

#3 GitHub Projects for Scrum Teams

While GitHub is an awesome place to manage your code, it wasn’t initially the easiest place to manage a Scrum Team. Things improved in 2021 with the release of GitHub Projects. GitHub Projects now lets you create Sprints and manage Issues (aka PBIs or Tasks) with far more power. 

Let’s take a look at some of the great new things you can do… 

  • Track Sprints 
  • Track estimates 
  • Add custom fields to Issues 
  • Collate Issues from multiple repos 
  • Set up automated workflows for your Issues in a project 

Note #1: That’s a tonne of awesome features… but it requires a bit of set up, follow these steps to get up and running: SSW Rules | GitHub Projects – Do you know how to do Scrum?  

Note #2: At SSW our Scrum teams is used to document their Scrum meetings (e.g. Sprint Reviews and Forecasts), by sending an email to the Product Owner with the Team cc’d. These days, this step can be done using GitHub Issue Templates. We also have a pretty cool guide for setting up your Scrum templates here: SSW Rules | GitHub Issues – Do you create a template for your Sprint Reviews, Retros and Forecasts? 

Good example of GitHub Projects
Figure: Good example – GitHub Projects gives you much more powerful project management ability 

#4 Questions – don’t bundle them in with your issues!

Do your customers know where to put their questions during a project? Sure, they can just add them to your issues, but a better way is to add them to your discussions. If customers don’t know to do that, you should give them a link, it will make it easy for them to find. You can also add a “Contact Us” to make it easy for them to reach out if they need $ paid support.

Good example of good GitHub Project templates
Figure: Good example – you can clearly see where to add your questions, support and feature requests.
They will not get mixed up with your Issues! Also, there is also a nice “Contact Us” section for when clients need help.
See https://github.com/sswconsulting/ssw.GitHub.Template/issues/new/choose

#5 GitHub Issues – Use Labels

GitHub Projects has a really nice way to organise issues. You can add extra fields, add estimates and put in labels. Labels are an important way of categorizing your GitHub Issues. However, it is critical to make sure they are useful, clear and not too many (so as to not overwhelm users). If you have too many labels your team will feel like they’ve fallen into what I call “label hell”.

The goal is to use consistent labels across all repos. Let’s take a look at how to make a simple, yet information rich set of labels…

Firstly, set up some GitHub Issue Templates that have default labels. Prefix those ones with “Type:” so it is clear they define the type of Issue:

  • Type: Bug
  • Type: DevOps
  • Type: Documentation
  • Type: Feature
  • Type: Refactor

Also, add some extra labels for important ancillary information. Try not to go overboard though, a good example might be 3. Some labels to define the area of work:

  • Area: Frontend
  • Area: Backend

And the standard GitHub label to indicate it is a good Issue for developers new to the project:

  • Good First Issue
Bad example of GitHub Project labels
Figure: Bad Example – using Effort labels is not ideal since the release of the new GitHub Projects
Good example of GitHub Porject Labels
Figure: Good Example – Add a few labels beyond the ones that are set based on the Issue Templates

Interestingly, even though devs like using emojis on things like Backlogs – they don’t seem to like them on Labels. That’s just going too far! 😂

Kevin Hart meme
Figure: Most of my devs think Emoji’s on labels is just too much!

You can learn more about where Effort labels are appropriate with GitHub Projects, which has custom fields.

What do you think? Are Emoji’s in labels, ok? Let me know in the comments.

What a great Christmas present from GitHub, enjoy, I’ll see you in the New Year!