How to manage a project using Github

This will be a series of two posts about how to manage our projects using GitHub, first notice the differences between the two of them, we differenciate between manage our code and manage our project.

The difference between those two are basically: the first one will help us to manage our issues focus on our priorities and achieve our goals and the second one will helps us to track our code changes, have a relialable version control code, easy to understand and to follow using in these case GitHub.


Introduction

We'll see how to use GitHub Issue system to manage our projects, this will be a post that will give you the basis to start with and I hope you will get the idea that will allow you to create your own workflow and manage your projects and by then your roadmap, users issues, new features, bugs and in the end have a stable methodology in which everyone could count on.

This is not about the tool it self, it's much more, it's about the methodology we are using to manage our projects. These methodology could be use without tool, this have beening written having in mind GitHub Issue but it's not a requirement.

Think about it as PSR2 for PHP or PEP8 for Python it's like a code style guide to be followed by the rest of the team and let everyone be on the same page.

There are three basic elements on GitHub that we'll interact with:

  • Labels
  • Milestones
  • Meetings

There is something else that worth to mention and it's the fact that this whole methodology could be modified and changed as we please and we should do that to adapt it to our company needs.

Labes

A GitHub issue could have any number of tags (labels) this will allow us to have a very granular categorization system for each ticket (issue), it's recommended to use the following tip and trick and group the labels into different categories, this will give us even more orden when organizing our labels:

  • Effort
  • Priority
  • Audience
  • Information
  • Status
  • Type

Each of those categories will be represented with a letter in front of the label name as shown below:

...
a:user  
a:doc  
p:blocker  
p:important  
...

You could use another nomenclature to identify each category for example instead of each letter use something more descriptive, like audience, effort, priority, type you get the idea, but personally I would prefer keep it simple and because is something that is not gonna change frecuently it's something easy to use.

This is an interesting script to standardize labels between GitHub repos.

Effort

Could be used to have an idea about how much time will take to close the ticket, giving us visibility on track time and velocity over the sprints using the effort as story points on an Agile team.

Priority

The label it's self explanatory but basically will be useful to give a level of relevance to a ticket so the team will know which ticket it's more important than others. Here p:blocker it's a label to have in consideration, those tickets should be fixed ASAP.

Audience

It will depend on the people, department or sections that a issue could affect directly, we could group these on users, customers and/or clients, we could use a specific department on our company like marketing, design or we could just make reference to a section of our project like documentation, there could be different audiences where we want to focus the issue to.

Information

Could be use to give extra details about the ticket, like for example how many percentage have been done already like i:progress-50

I personally don't tend to use this one to much unless you need to track your issues a that level.

Status

Could be use to know the state of an ticket a specific time, like for example when someone ask for feedback, we could have a label could i:feedback-needed so we could easily filter all tickets that needs feedback a in one go give our feedback.

I'll say the most important label here could be s:needs-discussion because this one will be use it frecuently in our triage meetings explained above.

Type

This tagging system will be used along side GitHub filtering system and that will allow us to granularize our ticket's queries as we please. Like for example if we want all the tickets that are opens and are relates with our product documentation section, we'll do a search like:

is:open is:issue label:a:doc  

The following are some of the labels that we recommend, actionable labels, we think these group of labels are enough to represent most of the scenarios but again this will relay on our needs.

Priority and effort are two of the most important labels category

e:1  
e:2  
e:3

p:blocker  
p:critical  
p:normal  
p:high  
p:low

a:admin  
a:consumer  
a:curator  
a:source  
a:marketing  
a:design

i:progress-25  
i:progress-50  
i:progress-75

s:feedback-needed  
s:needs-discussion

t:bug  
t:feature  
t:idea  
t:improvement  
t:invalid  
t:question  
t:support  
t:task  

The following are optional labels that I don't tend to use:

s:confirmed  
s:deferred  
s:help-needed  
s:incomplete  
s:rejected  
s:resolved  
i:fix-committed  
i:in-progress  
i:in-pull-request  

Complex taxonomies of bugs could let us in a situation where tags will be used to assert things about process that need to be communicated directly and explicitly and via a two-way channel.

And last but not less important comment that it's important that we stick to the label system that we got at the minute and do not modified this without previous discussion. Adding new labels could be tented but if we do so we could end with a labelling system messy and without sense.

Milestones

The issues give us our first run at an agenda. I recommend that there will be always at least 3 Milestones open and a maximun of 4 open, as follow:

  • Next Iteration
  • Next Tasks
  • Blue Sky
  • Making People Happier

Next Iteration

This milestone will answer the following question: What are we doing right now?

This could have any name we want, maybe a name related with the goal we wanted to achieve for this spring and of course a description.

Next Tasks

This milestone will go inside the category of things we aren’t we doing right now? but inside of the stuff we’ll probably do soon.

Issues that aren't part of the upcoming milestone, but should be re-triaged when that milestone has been reached.

Blue Sky

This milestone will go inside the category of things we aren’t we doing right now? but inside of the stuff we probably won’t do soon, basically it will be an idea collection area.

Arguably we shouldn’t create a bucket for things we don’t want to pay attention to

This is a bucket for everything we'd like to do someday, but have no current plans or schedule to implement.

Making People Happier

Stuff that people want. We could use this to know which are the most required features and use the :+1: system to vote those features the user like the most.

Meetings

Typically, Triage Meetings takes place 1-2 times a week it's a reunion to discuss issues and use the below workflow:

Go over all issues with a need discussion label

The label needs-discussion will be our special label and it will be use as the start point for each meeting. needs-discussion have to be used liberally, could be for big things or just small doubts.

We'll first go over all issues with the label needs-discussion we could use the following filter:

is:open is:issue no:milestone -label:s:needs-discussion  

We'll discuss all those labels and resolve them either but removing the needs-discussion label and moving the issue to a milestone or by keeping it if the discussion wasn't resolve so we could come back later on to the issue again.

Go over all issues that doesn't have milestone

Using the following filter, we can view in one go all the issues that doesn't have a milestone.

is:open is:issue no:milestone  

So we can assign a milestone to them.

Starting a new iteration

When we’re ready to start planning the next iteration we’ll create a new milestone, and only deliberately move things into that milestone.

We agree in a goal a create a new milestone

Sometimes if we’re not sure what our goal for the next iteration is we’ll create a ticket, “decide on goal for the next iteration” (and mark it needs-discussion of course).

 Assign issues

All issues in the current itertion should be assigned to someone.

 Maintaing the tickets

Keep the tickets up to date

Ticket life

Tickets have a limited lifetime or at least they should. When the description and/or the title is no longer what the issue was created for it's time to do some refactoring here and even open a new issue and close the original with a reference note or we could choose the other option and edit the title or description, however I do not recomend this because then you will lose track and visibility of that issue, people won't be notify about those changes and if we are changing the meaning of an issue they should know that now there is a new issue with a different goal.

Minor changes that doesn't change the meaning of the issue on the title and description are more than welcome so we can keep thing clean.

Long tickets

A good practise when the comments on a thread go crazy it could be handy open a new issue to split all that craziness from the resolution of the discussion, because it's gonna be hard to find how it got fixed in between all those comments.

Sometimes comments on a ticket could change the meaning of the issue so it could be then usefull to create a new ticket pointing to the old one a close it.

Comments should indicate additions and clarifications

It's important that tickets got a good and self explanatory title and description. As well as is important Referencing and Association properly.

Referencing and Association

Notice that issues can be associated with each other adding the number of the other ticket, this use to be precede by a group of key words Close, Relate, Duplicate that will give us an insight of what that association is for.

As a part of this association it will gives you the status of the associated issue, very useful.

 Group tickets

The association explained before could be used for grouping tickets:

Sometimes we need to create a master issue: an issue that will links to all the sub-issues that need to be finished.

Instead we list all the bugs in the main description of the master issue, and edit as necessary. You can use [ ] to make the bug list a checkable list. Unfortunately issue links don’t get crossed out when they are closed (but they should, that would be a very helpful improvement).

Take care with it’s easy for your master issue to get out of sync with the sub-issues.

 Conclusion

I would say there should be at least three rules that everyone should have in consideration:

  • Do not create new labels without discussing it first
  • Do not create new milestones without discussing it first
  • Discussing everything so let's meetup :)

I should add another one to that list edit everything but I won't just to keep it simple to remind, but this one it's important as well as, there are just few cases where we shouldn't be editting issues and that's when we need instead to create a new issue (as explained above).

You will notice that I haven't talk about priorities, severitues and estimations those are thing that you could track if you wish but personally I think we'll end with a bunch of extra labels that will be difficult to maintaing just because it will be overkilling and GitHub doesn't offer us out of the box the features needed for implementing these in a no intrusive way with our labelling system which will give us the ability to maintaing them easly. Basically we'll end with a result that we won't be able to trust because it's gonna be diffuclt to keep it accurately.

It’s better to give people more power: it’s actually helpful if people can overreach because it is an opportunity to establish where the limits really are and what purpose those limits have.

 Resources

Definitions

Tools

An interesting tool that will automate some of the process explained before, as for example the effort labels some of the status labels could be represented by the Kaban board that ZunHub offer us, it could worth dedicate a post explaining how ZenHub modify and by then improve our workflow when working with GitHub.