At Lullabot, we’ve been using GitHub, as well as other project management systems for many years now. We first wrote about managing projects with GitHub back in 2012 when it was still a bit fresh. Many of those guidelines we set forth still apply, but GitHub itself has changed quite a bit since then. One of our favorite additions has been the Projects tab, which gives any repository the ability to organize issues onto boards with columns and provides some basic workflow transitions for tickets. This article will go over one of the ways we’ve been using GitHub Projects for our clients, and set forth some more guidelines that might be useful for your next project.
First, let’s go over a few key components that we’re using for our project organization. Each of these will be explained in more detail below.
- Project boards
- Epics
- Issues
- Labels
Project boards
A project board is a collection of issues being worked on during a given time. This time period is typically what is being worked on currently, or coming up in the future. Boards have columns which represent the state of a given issue, such as “To Do”, “Doing”, “Done”, etc.
For our purposes, we’ve created two main project boards:
- Epics Board
- Development Board
Epics Board
ex: https://github.com/Lullabot/PM-template/projects/1
The purpose of this Project board is to track the Epics, which can be seen as the "parent" issues of a set of related issues. More on Epics below. This gives team members a birds-eye view of high-level features or bodies of work. For example, you might see something like “Menu System” or “Homepage” on this board and can quickly see that “Menu System” is currently in “Development”, while the “Homepage” is currently in “Discovery”.
The “Epics” board has four main columns. (Each column is sorted with highest priority issues at the top and lower priority issues at the bottom.) The four columns:
- Upcoming - tracks work that is coming up, and not yet defined.
- Discovery - tracks work that is in the discovery phase being defined.
- Development - tracks work that is currently in development.
- Done - tracks work that is complete. An Epic is considered complete when all of its issues are closed.
Development Board
ex: https://github.com/Lullabot/PM-template/projects/2
The purpose of the Development board is to track the issues which are actionable by developers. This is the day-to-day work of the team and the columns here are typically associated with some state of progression through the board. Issues on this board are things like “Install module X”, “Build Recent Posts View”, and “Theme Social Sharing Component”.
This board has six main columns:
- To do - issues that are ready to be worked on - developers can assign themselves as needed.
- In progress - indicates that an issue is being worked on.
- Peer Review - issue has a pull request and is ready for, or under review by a peer.
- QA - indicates that peer review is passed and is ready for the PM or QA lead for testing.
- Stakeholder review - stakeholder should review this issue for final approval before closing.
- Done - work that is complete.
Epics
An Epic is an issue that can be considered the "parent" issue of a body of work. It will have the "Epic" label on it for identification as an Epic, and a label that corresponds to the name of the Epic (such as "Menu"). Epics list the various issues that comprise the tasks needed to accomplish a body of work. This provides a quick overview of the work in one spot. It's proven very useful when gardening the issue queue or providing stakeholders with an overall status of the body of work.
For instance:
Homepage [Epic]
The Epic should also have any other relevant links. Some typical links you may find in an Epic:
- Designs
- Wiki entry
- Dependencies
- Architecture documentation
- Phases
Phases
Depending on timelines and the amount of work, some Epics may require multiple Phases. These Phases are split up into their own Epics and labeled with the particular Phase of the project (like “Phase 1” and “Phase 2”). A Phase typically encompasses a releasable state of work, or generally something that is not going to be broken but may not have all of the desired functionality built. You might build out a menu in Phase 1, and translate that menu in Phase 2.
For instance:
- Menu Phase 1
- Labels: [Menu] [Epic] [Phase 1]
- Tasks
- Labels: [Menu] [Phase 1]
- Menu Phase 2
- Labels: [Menu] [Epic] [Phase 2]
- Tasks
- Labels: [Menu] [Phase 2]
- Menu Phase 3
- Labels: [Menu] [Epic] [Phase 3]
- Tasks
- Labels: [Menu] [Phase 3]
Issues within Phase 3 (for example) will have the main epic as a label "Menu" as well as the phase, "Phase 3", for sorting and identification purposes.
Issues
Issues are the main objects within GitHub that provide the means of describing work, and communicating around that work. At the lowest level, they provide a description, comments, assignees, labels, projects (a means of placing an issue on a project board) and milestones (or a means of grouping issues by release target date).
Many times these issues are directly linked to from a pull request that addresses the issue. By mentioning the issue with a pound(#) sign, GitHub will automatically create a link out of the text and add a metadata item on the issue deep linking to the pull request. This is relevant as a means of tracking what changes are being made with the original request which then can be used to get to the source of the request.
For our purposes, we have two "types" of issues: Epics or Tasks. As described above, Epics have the "Epic" label, while all others have a label for the Epic to which it belongs. If an issue does not have a value in the "Project" field, then it does not show up on a project board and is considered to be in the Backlog and not ready for work.
Labels
Labels are a means of having a taxonomy for issues.
We have 4 main uses for Labels currently:
- Epic - this indicates the issue is an Epic and will house information related to the body of work.
- [name of epic] (ex: Menu) - indicates that this is a task that is related to the Menu epic. If combined with the Epic label, it is the Menu Epic.
- [phase] (ex: Phase 1) - indicates this is part of a particular phase of work. if there is no phase label, it's considered to be a part of Phase 1.
- bug - indicates that this task is a defect that was found and separated from the issue in which it was identified.
- Blocked - Indicates this issue is blocked by something. The Blocker should be called out in the issue description.
- Blocker - indicates that this issue is blocking something.
- front-end - indicates that an issue has the underlying back-end work completed and is ready for a front-end developer to begin working on it.
There are other labels that are used sometimes to indicate various meta, such as "enhancement", "design", or "Parking Lot". There are no set rules about how to use these sort of labels, and you can create them as you see fit if you think they are useful to the team. Though be warned, if you include too many labels they will become useless. Teams will generally only use labels if they are frictionless and helpful. The moment they become overwhelming, duplicative, or unclear, the team will generally abandon good label hygiene.
These are just some guidelines we consider when organizing a project with GitHub. The tools themselves are flexible and can take whatever form you choose. This is just one recommendation which is working pretty well for us one of our projects, but the biggest takeaway is that it’s versatile and can be adapted to whatever your situation may require.
How have you been organizing projects in GitHub? We’d love to hear about your experiences in the comments below!