Notifications: GitHub’s most underrated feature
Most people seem to think the little bell in the corner is noise but I see it as the path to hyper velocity.
I stand corrected: most people I’ve asked have no idea what the Notifications page on GitHub is! The most common refrain is “there’s so much here I can’t get through everything.” Another issue I hear is “I wait to get an email from GitHub” (which goes right in the trash). So what is this mysterious page and how do we turn it into something awesome for developers?
Watch only the repos you actually contribute to
The first complaint about the Notifications page is that it’s too noisy. Are you still following that open source project from 2012 when you found a spelling bug in their Readme? That’s a good candidate to remove.
Or if you’re at a bigger company like me with lots of repos, maybe you don’t need to see what’s going on in every single one of them. Do you contribute or read code from a repo? Definitely watch it. Otherwise I’d recommend filtering out the repos you watch so you have a clear list of notifications.
An easy way to do this is to navigate to the Watching tab next to the Notifications tab and do a quick audit of which repos you actively contribute to. As you can see from the screen above, I am following way more repos than I manage and contribute to. Maybe it’s time for me to do some delayed sprint cleaning…
Don’t know where to start? Check “Participating”
Every time I show people this tab they’re astounded that it even exists. The Participating tab on the Notifications page will show you only the Pull Requests where you are a Reviewer. If the Participating tab has a number next to it greater than zero it means someone is waiting on you to review their code.
If you do nothing else, set a bookmark to the Github Participating Notifications page so you’re always one click away from seeing who needs your attention.
Smash that Open button
Is that Participating count higher than you hoped for? Dreading opening new notifications? Github has you covered:
Click that Open all unread in tabs button and magically the notifications on the current page will open in new tabs so you can review each one. If you did this on the Participating tab and not the Unread tab it will be a better experience on you and your browser.
All caught up on reviews? Clear out that inbox
Pat yourself on the back: you reviewed your team’s code! But what do you do with the mountain of unread notifications you aren’t involved in? Should you still take a look? Could it be important? Give yourself a break and hit the Mark all as read button.
Once you have a clean inbox you can begin to proactively review your team’s code but for now let’s crawl before you run. Inbox Zero can do wonders for anxiety so cut yourself some slack and start with a clean slate.
Kick your reviews into high gear with statuses
Now that you’ve reviewed the necessary code you are participating on, removed the unnecessary repos you don’t need, and cleared out your unread notifications with the other non-essential reviews, it’s time to make your reviewing habits streamlined. Github status colors are a super fast way to see what needs your attention.
See these colors to the left of the Pull Request titles? These are your fast track to PR bliss. Red links show closed PRs and most of the time you can straight up ignore these. The code isn’t changing, so unless you wrote the PR and someone else is closing it for you, you probably don’t care why.
Purple links show merged PRs. If you were participating in approving this Pull Request, then this is an accounting metric to let you know the code is merged to master. Again, you can skim this and mark it read with the check mark to the right of the Pull Request title since the purple link alone will tell you pretty much all you need to know.
The two colors you actually care about are green and gray.
Green PRs are open and awaiting approval. If you see a green link then you have some action to take (like responding to a comment or providing a review).
Similarly, gray PRs are for drafts, Github’s relatively new feature to discuss Pull Requests that aren’t ready to merge yet. These aren’t as important as green links because no immediate action is required. Nonetheless, you should still investigate these Pull Requests for two reasons:
- It’s big or controversial. If it wasn’t, it likely wouldn’t need a draft to discuss in the first place.
- The Requester is asking for feedback. Draft PRs can’t be merged so the only reason to have them open is for others to discuss before being subjected to an official review. If no one reviews a Draft PR, was it really worth creating in the first place?
Reduce cycle time with this workflow
If your team tracks performance or follows Kanban then you’re probably looking for ways to reduce cycle time (i.e. the measure of how long it takes for code to get from a Pull Request to merged into your master branch). With the above workflow, checking notifications becomes an automatic, continuous activity.
This workflow enables me to stay up-to-date on my teams’ code changes. These days I never go more than 30 minutes without seeing new code I might need to review. This means that developers wait less time to get reviews and feedback which decreases cycle time and improves the speed with which we can ship code.
Waiting for reviewers is a real drag on the team. With this improved Github workflow your developers will never have to wait too long to see a review. And less time waiting makes for happier and more efficient developers.
Do you have any other tips on how you work with Github? Leave a comment below or send us a tip on Twitter.
