Communicating progress on GitHub

We all love GitHub. However, their issue system was created with Open Source in mind. That's why sometimes we struggle when using it for things that it wasn't conceived for.

An example of this are long, big activities; Issues are great for small to medium focused tasks but for bigger picture things they don't work so well. This is especially true when work needs to be done across different repositories and/or teams. On top of that you end up with a mixture of bugs, strategic tasks, and ongoing development efforts all in the same bucket. This makes the issue list very hard to digest and use no matter how smart your labeling system is.

Obviously there are alternatives, tons of project management tools have been built to cover this and most of them integrate with GitHub. We tried several of them but we kept coming back to the same problem: we are so used to GitHub being our daily dashboard, the first and only place we go to, that we kept forgetting to keep them up to date.

So we decided to get a little bit creative…

Project issues

Some months ago Anthony wrote an amazing blog post about how we decide what work to take on at DNSimple. There you can read how any project that we consider has a corresponding issue on our business repository.

Initially this issue is simply a proposal with some big picture information about the goals to accomplish. Once the proposal is accepted and someone starts to work on it, the issue becomes the perfect place to keep track of the progress being made:

• The description of the issue is extended and updated as needed along the project.
• Comments are used to notify teammates about meaningful events.
• Work is undertaken in smaller issues across different repositories as needed, and cross-referenced there.

The project issue becomes the place to go if you want to get a sense of where project is going.

Index issues

In most cases the amount of work to be done is small enough that a single issue is enough to keep track of it. Then there are those other ventures, projects that are so big that keeping track of everything in a single place would render it unusable.

In those cases we apply the good old divide and conquer. Before starting the job we split it up in parts. It doesn't matter how or how many. The important bit is that these pieces are roughly the same size. Don't worry about getting them wrong (you will). It's fine to come back and reorganize these phases as needed.

When we are about to start working on one of these chunks we create an Index Issue and link it from the Project Issue. This issue will effectively become the equivalent of a project issue for that specific phase. We will update it and link all the ongoing tasks in there. Once completed, we will close it and update the Project Issue accordingly.

With Index Issues you keep track of the work being done on the different phases of a project. The Project Issue then holds the information about the pieces the project is composed of and how far we are to completing them.

GitHub's projects and milestones

To be honest we have given them different uses and several tries. The truth is that we never felt comfortable with them for this specific use.

Meetings

Although we do have meetings to communicate progress from time to time, we favor asynchronously written communication. As you know, DNSimple is a remote company and we are spread across different time zones. By keeping track of all these things on GitHub we ensure all team members have access to the state of a project even if they weren't around when a meeting took place.

Share on Twitter and Facebook

Javier Acero

Programmer. Minimalist. Apple fanboy. Currently having fun at DNSimple. I love coffee and my cat.