Dear GitHub: Please Improve Your Notifications

An Open Letter to GitHub

[Update 8/6/2012: good news. GitHub has just released a complete overhaul of their notification system. After reading the blog post about it, it looks as if they have fixed most or all of the issues I raised in this post. It looks like a lot of thought and hard work went into this change. Thanks for listening, GitHub.]

Dear GitHub,

Hi guys!

Guess what: GitHub’s great. Yeah, you know that.

But hey: could you please fix GitHub notifications? They seriously suck. No, really, I mean it. They’re the worst. Sorry, I don’t mean to hurt your feelings. I know a human being designed the notification system.

GitHub notifications are a productivity sink. Despite having fifteen checkboxes for customization in the Notification Center, I still can’t make them work in a way that helps me. Don’t get me wrong, I am not asking you to fix it by adding more checkboxes to the list. I am asking for an overhaul of how the notification system works. Below I will try to clearly lay out the problems I see and what I would like the system to do instead. The overall goal is to change notifications from a productivity sink to a productivity boon.

First I will describe myself and how I use GitHub, to help you decide if I am the kind of customer you want to serve. I understand that an important part of running a successful business is that you can’t be all things to all people. So here’s me:

  • I am an independent software consultant doing Ruby and JavaScript programming. I have a long-term gig at a company that has 81 private repos on GitHub. I am part of their GitHub Organization so I have access to all the repos. Combined, these repos get a ton of activity–there are probably about thirty developers working on them full-time.
  • The company I work at uses GitHub for code reviews, too. People sometimes post in-line comments in the code reviews.
  • I have written some open source software. Not a ton, but a few little things. I host them on GitHub. This has worked out well for me. All Ruby and JavaScript.
  • I am also the maintainer of an open source software project that someone else wrote in Python and posted to a bulletin board. It’s for exporting iPhoto pictures to a folder structure. I wanted to make some changes for myself but let other people make changes too, so I posted it to my GitHub account. It has become popular enough that I get a pull request once every few months. I try to respond to them and pull them.
  • I participate in the occasional issue discussion on the Rails repo and a few other repos.
  • When I’m at work I want to be notified about events related to work but not be distracted by the open source projects I work on (except during the occasional break from work).
  • When I’m at home I want to be notified about events related to the open source projects I work on but not be distracted by work-related events (except when I occasionally check to see if anything’s going on while I’m out).

Ok, so that’s me. I would characterize my use of GitHub as heavy–every hour of every workday–in my professional work and light-to-medium in my open source work.

So How Can GitHub Notifications be Improved?

Well, these things would help:

  • In the Notification Center I want to set up preferences at two levels: one for projects I’m Actively Involved in and another for projects I Occasionally Participate in. For example if I submit a pull request for any repo, whether I’m Actively Involved or not, I want to be notified of comments on my pull request. But I only want to be notified of pull requests from other people on the projects I’m Actively Involved in.
  • Every new repo someone else creates is assigned the Occasionally Participate level for me. Every new repo I create is defaulted to the Actively Involved level for me. These statements are true whether the repo is Public or in an Organization I belong to.
  • For any repo I have access to, I can change whether I am Actively Involved or Occasionally Participate.
  • These levels will be especially helpful for the work I do in an Organization. I can stay updated on events in the two or three repos I use daily but prevent spam on repos in my organization but that I never touch. I’d like to see pull requests for my active repos but not for all repos in the org.
  • I want the dark gray Unread Notifications icon at the top of every page to reflect the current Context (personal, organization #1, organization #2). Hovering over it would quickly show the notification count for each context. The counts in that tooltip should be clickable to go to the Notification Center for that context.
  • I want the Notifications page to show me only the notifications for the currently selected Context. (Myself or whatever Organization context I’m currently in.) And it should be easy to switch to a different Context from that page.
  • I want to specify one email address for my own account’s notifications, another email for my organization #1 notifications, another for my organization #2 notifications, etc. It’s really frustrating that I need dozens of rules in my personal GMail account to forward GitHub notifications to the correct work email accounts.
  • I want the notification emails to include the other user’s full name in the From field. It’s ok to still include the GitHub username but please also include their real name, just like you do on the user’s home page. E.g., my email client should tell me the email is “From: defunkt (Chris Wanstrath).”
  • I want the notification emails to provide more context about exactly what happened. The emails are horrible! It’s impossible to tell from the Subject line or even the Body what happened. What am I being notified about, exactly? Oh, somebody filed a pull request? For Pete’s sake would it hurt to tell me that without forcing me to look at the URL at the end of the email? Right now the subject line is the title of the pull request, the body is the body of the pull request, and that’s it. I’m expecting the words “Pull request” (or whatever the notification is about) in the email subject line AND at the top of the body.
  • And don’t even get me started about emails telling me about comments on commits. The emails say nothing about the code being commented on or who made the commit. The subject line should mention if it’s “on your commit” or “on defunkt’s (Chris Wanstrath’s) commit.” Notice I used the username and real name. And I want to see this in the body:
    • The surrounding code that’s being commented on.
    • The comment.
    • The line where the comment was made.
    • Who made the commit! Was it me? Sheesh. (Username and real name.)
    • Who made the comment. (Username and real name.)
  • I want email notifications to include a link at the bottom: “Delete this from the Notifications page.” I want to click that link from my email program and have it kick off a URL that deletes the notification off GitHub so I don’t see it again the next time I go to the Notifications page.
  • I want every notification–in email and on the Notifications page–to tell me why I was notified. E.g., “You received this notification because you have turned on Comments on commits in MegaCorp repositories.” The link takes you to the page where you can turn it off. Doing this on the Notifications page will be tricky because you don’t want to clutter up the page too much. Just show me a tiny question mark on the row so I can hover over it and see the explanation in a tooltip.
  • I want the Notifications page to have a link right at the top that says “Edit Notification Settings” and takes me to the Notification Center tab of the Accounts page.
  • If I delete all the notifications one by one on page 1 of the Notifications page, it should not look like I have emptied out my notification list. It should be clear that there are more. How about an AJAX UI that pulls in the first row from the next page and adds it to the end of this page each time I delete one?
  • Related: if I delete all the notifications on p. 1 and click Next to go to the next page of notifications, it should not skip past the new first page of notifications. I.e. it should show me the notifications after the last one I deleted. This won’t even be necessary if you do the AJAX UI I mentioned.
  • When I am cleaning out my notifications in the Notifications page I want to be able to see at a glance–without drilling down on the notification–what each notification is about. I should see all of the following. Some of your notifications do include all of them but some don’t. The ones that don’t are very frustrating. E.g., “So-and-so discussed a commit 3 hours ago.” Really? Thanks. In what repo? Come on. Are you really going to make me guess? And was it my commit or someone else’s?
    • What repo was affected
    • Who took the action I’m being notified about (username, real name, and little avatar)
    • What the action was (commented on my commit, submitted a pull request, …)
    • When it happened
    • A one-liner about the event (the pull request subject, first line of the comment, etc.)
    • If it’s a pull request, what is its current status? (Open, Closed) In other words, did someone already pull it after it was added to my inbox?
  • I want the Notification Center to let me turn off not just email notifications but also notifications in my Notifications page. I really don’t have time to care about things that happened in about 78 of the 81 repos my organization owns. And when my Notification icon is showing me big numbers of unread notifications, it’s the Little Boy Who Cried Wolf. I end up having to ignore the dang notification icon because so many of those notifications are irrelevant to me. And you know what that means: when a real big bad wolf comes into town, I will ignore the cries for help and the po’ little boy will be eaten. (Or I might not respond to a notification I should have known about.)
  • A note on that last point: I know it would be confusing to have two checkboxes for each notification type (one for the Notification page and another for whether you want to get email). You can avoid Checkbox Overload with this simple fix:
    • Keep the checkbox at the top titled “Receive email notifications (global setting).” This would control whether I get email notifications at all.
    • The event-specific checkboxes in the list should not be labeled “Email.” They should be labeled “Notify.” If I check a box, I want that notification in my Notification page–and by email if the box at the top was checked. If I don’t check the box, I don’t want either.
  • I want to mark individual notifications as Read or Unread from the Notifications page.
  • You’ve been adding a lot of nice shortcut keys to GitHub pages lately. I want to navigate the Notifications page with keystrokes, a la GMail. j=down, k=up, o or Enter=open, U=mark as unread, I=mark as read, #=delete (or maybe y).


I know that’s a lot of stuff. But it sure would help. Really. It would help a lot. GitHub would be a much more useful tool, especially for people in Organizations. And look, I gave your product manager a big head start with this list.

If you want to start with something simple that gives you a lot of bang for the buck, please just fix the subject lines of the “discussed a commit” notifications on the Notifications page. Give us this:

defunkt (Chris Wanstrath) discussed a commit on membername/reponame 1 day ago

instead of this:

defunkt discussed a commit 1 day ago

See the two differences? I included the person’s real name and mentioned what repo is being discussed.


4 thoughts on “Dear GitHub: Please Improve Your Notifications”

  1. Update: added the “If it’s a pull request, what is its current status?” point to the list of info I want to see at a glance in the inbox.

Leave a Reply

Your email address will not be published. Required fields are marked *

Feel free to use <a>, <b>, <i>, <strong>, <em>, <strike>, <code>.

Code blocks:
[code language="ruby/javascript/html/css/sass/bash"]