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
- How to manage a project using GitHub
- How to manage our code using GitHub <-- still working on this one
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.
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
methodologywe are using to manage our projects. These
methodologycould 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:
There is something else that worth to mention and it's the fact that this whole
methodologycould be modified and changed as we please and we should do that to adapt it to our company needs.
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:
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
typeyou 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.
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.
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.
It will depend on the people, department or sections that a issue could affect directly, we could group these on
clients, we could use a specific department on our company like
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.
Could be use to give extra details about the ticket, like for example how many percentage have been done already like
I personally don't tend to use this one to much unless you need to track your issues a that level.
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.
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.
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
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.
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.
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.
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
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).
All issues in the current itertion should be assigned to someone.
Maintaing the tickets
Keep the tickets up to date
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.
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
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.
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.
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 everythingbut 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
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.
- How Ionic uses GitHub better
- Managing Projects with GitHub
- Using GitHub for Project Management
- How We Use GitHub Issues To Organize a Project
- Smashinbgboxes - Using GitHub issues to Manage Projects
- Web Project Management and Collaboration Using GitHub
- Stackoverflow - When to have bug triage meetings in SCRUM process?
An interesting tool that will automate some of the process explained before, as for example the
effort labelssome 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.