Integrating GitHub Sponsors

February 15th, 2021

This week's format of "Building Lotus" newsletter is going to be different. Usually when I sit down to write a newsletter, I know what I want to share and tell you about, more or less. Not today though.

Right this second, all I have is an idea and we're going to think it through and prototype it together. Let's go.

Idea

GitHub has a great new feature called Sponsors. Users can sponsor maintainers of their favorite open source projects by donating various sums of money every month.

Wouldn't it be cool if maintainers could know when a person who created an issue or a pull request is sponsoring them?

So that's the idea, highlight notifications from your sponsors and move them to the top of your inbox.

Full disclosure: this idea isn't mine. I saw it in triage - an awesome CLI for managing GitHub notifications by TJ Holowaychuk. I thought this feature could be really nice to have in Lotus, so I emailed TJ and asked if I could borrow it and he kindly said yes. Thank you, TJ!

Thinking out loud

Since the idea is to move notifications from sponsors to the top, it could have negative effects for your inbox - a lot of notifications could occupy the top of the inbox constantly.

Some popular maintainers like Sindre Sorhus, Caleb Porzio and Evan You have more than a hundred sponsors. If Lotus would prioritize every notification from their sponsors, their inbox would most likely be ruined.

However, GitHub allows maintainers to set up sponsorship tiers. For example, Caleb has these tiers:

He offers priority support only for the "Platinum Sponsor" tier:

Bugfix priority (if there's a bug you need to be fixed, it gets bumped to the top of the pile)

Lotus can't automatically detect which tier you decided to provide priority support for, so we'd need a UI for manually selecting that tier. I really want Lotus to have a small set of settings, but unfortunately there's no way of working around it. I also realized now that user may need to select more than one tier they want to provide priority support for. The UI just got more complicated before I even drew the first pixel, haha!

I also think that sponsors on the other tiers deserve a little shout-out as well, even if their notifications won't get to the top of maintainer's inbox. Perhaps Lotus could show a little heart icon near the notification title to signal that this notification is coming from a person who's sponsoring you. Heart icon should be recognizable too, because GitHub also uses the same icon in their "Sponsor" buttons.

Another important thing to consider is that not all maintainers offer priority support or they may not be interested in those heart icons. A feature should be turned on by default if it's equally valuable to at least 90% of users and this one certainly doesn't fall into that bucket.

Side note, if 90% of Lotus users had a large number of people sponsoring their open source work, world would be a little better. One can hope!

Scoping down

Here's what would have to be done to ship this feature in full:

I'm going to be honest, that's a lot of work for a feature that would be useful to less than 5% of Lotus users.

I'm going to go full Getting Real on this feature by scoping down and iterating on it continuously, instead of trying to ship the full version right away.

How would a scoped down version of it look like?

Wait, did I just cross off the part where notifications from sponsors go to the top of inbox? Yeah, because Lotus already has a feature that does the same thing - bookmarks. When you bookmark a thread, all future notifications for that thread will be on top.

Here's a screenshot from last week's newsletter that shows how it looks:

User would see a heart icon in the notification title, which would let them know it's coming from a sponsor. Then they can bookmark that notification, which would achieve the same "above the pile" effect that I initially planned with sponsorship tiers.

If that's going to be too much manual work for users, that means this feature actually has some audience and people need it. Then I could spend more time on it and implement the full version with support for tiers and automatic prioritization.

It's always easier to add stuff later than take something away from your users.

Prototyping

Alright, time for some pixels, I can't wait to see how that heart icon will look in the inbox.

At first I thought I'd use Excalidraw to sketch this, but because I'm not building this thing just yet, it's faster to prototype it in HTML. Plus, I get to see how it would look in the actual app, not in the wireframe.

Looks cute! I think there should also be a tooltip for a heart icon to be clear what it's there for.

There are also alternative ways to make sponsor notifications stand out. One of them is to replace the notification icon (issue, pull request, etc) with a heart, so that there's only one icon in the row.

It's not as noticeable as the previous version, but that could be a good thing. My other idea was to not add the heart icon and change the color of the existing notification icon to pink instead. However, I now see that it would be even less visible than this, so it's probably not the right way to go. I'm going to stick with heart icons on the right side for now.

The same icon could also be visible near the title when viewing each notification.

I think there isn't even a need for adding a setting for showing or hiding these icons, because it doesn't affect the functionality of the app in any way. The less settings are there, the better it is for everyone - developers and users.

There's a separate chapter for avoiding preferences in Getting Real, which clearly shows how often this mistake is made.

Decide the little details so your customers don’t have to

Spot on. I don't have anything to add here.

Summary

Is the scoped down version significantly less functional than the original idea? Not really. Lotus still highlights notifications from sponsors and it's up to you to decide whether you want to prioritize some notifications or not.

I think the idea of integrating GitHub Sponsors into Lotus is clear and I can evolve it into something more powerful over time.

By removing support for sponsorship tiers, I don't need to work on many things that would drag this feature off for a week. I will be able to ship it in a few days and iterate later. I can also spend more time on polishing it and adding some delight to the user interface. Would be cool to have some micro animation when you move the cursor over a heart icon.

If you read this far, I hope you enjoyed the details behind what goes into planning and prototyping each feature! Even though it's still not done, I thought it'd be interesting to try out this way of expressing my thoughts.

As it often happens in software development, even small things like moving list items to the top can be accomplished in multiple ways. It's important to balance between time and scope. Otherwise it's easy to get stuck in details that don't even matter at this point.

Just today I was working on a tool to compile Lotus for Intel and Apple Silicon Macs and I lost a lot of time trying to figure out how much functionality it should have.

I wanted it to handle everything: bump app version, build a Webpack bundle, run tests, compile binaries, upload them to GitHub and generate release notes. When in reality, I only needed it to compile binaries, because that was the original issue I needed to solve. Other things were nice-to-haves, but they weren't the problem.

I scoped it down and several hours later I had a working program that takes the source code of Lotus and produces binaries for Intel and Apple Silicon processors. Also, it has a kick-ass name too - EMP or electromagnetic pulse. I really, really like it. Planning to open source this project at some point once I use it in production for some time.

I'm curious about your opinion on the Lotus + GitHub Sponsors combo, let me know what you think! You can write me directly at vadimdemedes@hey.com or DM on Twitter.

See you next week!

– Vadim.

I'm building Lotus in the open and I'm sending out progress updates just like this one every Sunday.

I won't send spam and you can unsubscribe anytime.