How To Get Thousands of Stars on Your Github Project
I’ve made 5 ‘trending’ repositories and want to share my method
If you’ve ever open-sourced code, you know how difficult it is to get anyone to care. It’s weird, isn’t it? You spend hundreds of hours on something and want to give it away for free but nobody wants it.
The issue: your repository is in a chicken and egg situation where nobody will use it until it has stars, but it won’t get stars until people use it. The solution: make a really gorgeous and informative repo to get a few seed stars from people browsing Github. This is illustrated below:
Eventually you want stars to come from devs who’ve used your repo (side: “repo” is short for “Github Repository”), but to break the cycle you first need to get some stars. Any stars. That’s the aim of this article.
But first, a little about me! I started releasing open-source code about 6 months ago. Within that time, I somehow ended up on Github’s list for the top iOS devs in the world. I’m definitely not experienced enough to be on that list, so it feels like I genuinely found a loophole in the system. If anything gives me an edge, it’s that I also do design work, which you will see coming into play later. So, these are my trending projects:
- TinderSimpleSwipeCards (650+ stars, 6 months old)
- RKSwipeBetweenViewControllers (400+ stars, 4 months old)
- RKDropdownAlert (500+ stars, 4 months old)
- RKCardView (500+ stars, 2 months old)
- RKNotificationHub (500+ stars, 1 week old)
All five of them hit #1 on the Github trending pages, and I broke down the process of getting there into 6 steps.
[Edit (April 14, 2017): The star counts have since changed, RKNotificationHub has almost 3k stars now! Changed the title from “hundreds” to “thousands”]
The 6 Steps (secret sauce is in 4–6)
To keep this short, 1–3 will be brief, and 4–6 will be extensive.
- Projects are Everything
- Read and Research
- Building the Repo
- THE README
- THE GRAPHIC
- THE FEEDBACK LOOP
1. Projects Are Everything
Repos are products you build for developers
Products solve user problems. You often hear that founders create companies based on problems they personally encountered. Along the same train of thought, open sourced code solves developer problems. Now, how the hell do you expect to stumble into these problems if you aren’t constantly building things?
Pick up side projects, go to hackathons, fiddle with stuff on the weekends. Recognize where you are repeating code and where you just built something modular that other people might want.
2. Read and Research
Lots of problems have already been solved a hundred thousand bajillion times
The moment you think you have something repo-able, check to make sure someone else hasn’t done it first. If something exists, is heavily used, and is well made, move on.
If it hasn’t been done, or it’s been done poorly, great! Do your research. Look at existing solutions and find out what people don’t like about it. I love combing through Github Issues for clues as to how I should build my stuff. If you have the time, try to use their product and note any difficulties from using their documentation.
Finally, read through well written code. For example, I LOVE SVProgressHUD. In particular, I love that you can call it with a single line of code without building and maintaining an object. I ended up building RKDropdownAlert in a similar way.
3. Building the Repo
Say this five times fast: “simple, intuitive, usable”
One thing I’ve realized is that my later repos are growing at a much faster rate than my earlier repos did. It could be that more people recognize me now (I’m super famous in my head), but I think it has to do with my increasing laziness. When I first started, I wrote hundreds and hundreds of lines of code for minuscule optimizations. Now, I’ll build something decent and usable, and spend those hours cleaning up the interface instead.
Let’s use RKNotificationHub (RKNH) as an example.
I first conceived of RKNH when I built something similar for my main project’s menu button. At the time I thought it would be a great way to bug people into checking out new features, but it worked so well that the team started using it more.
The initial concept for the repo was a fully functional notification system. The idea was to link it to an object and have it intelligently update when that object changes.
Instead, I built a stupidly simple UI mechanism that shifted the logical burden to the developer, which actually gave them more control. Why? Because in the end I got lazy. But, I think it worked to my advantage. It’s simpler, light weight, very intuitive, and extremely usable.
Anyway, I want to get on to the non-obvious stuff, so here’s a one line summary: If nobody can understand how to use your code, nobody is going to use it.
4. THE README
The most important component of the entire repo
Finally, something more interesting. If you only take away one thing from this entire article, this is what it should be:
For every hour of code you write, spend an hour writing your README
I’m absolutely serious. In fact, I think my success on Github can be entirely attributed to the fact that I design my READMEs beautifully to make up for the fact that the code is unexceptional.
So here’s generally how I try to layout my READMEs (example):
A few key points
- THE MAJORITY OF PEOPLE GLANCE AND LEAVE. Make it pretty so that it’s easier for them to star before they leave. The more stars you have, the likelier it is that serious developers will use your repo.
- Images, images, images. Use LICEcap to make gifs when there are animations.
- Show, don’t tell. Don’t say “it’s a beautiful way of doing this thing”. SHOW them with a gif. Don’t say “super simple to use”. Show that simplicity with a code snippet.
- You MUST have a “how to” section. People won’t read your code, you have to hold their hand.
- Supplement any images with the code necessary to get the effect shown
- If someone opens an issue, fix it as soon as you can. If two people ask the same question, take the time to answer it somewhere on your README.
5. THE GRAPHIC
For the broad concepts, images > text
Put a graphic at the top of your README that communicates your repo’s purpose. If I drew some pretty graphics and had no code, I would probably still get 60% of the stars I’m currently getting. Wherever tech goes, design follows, and while open source is inherently a very tech-y place, it’s not a very design-y place. Thus, use graphics to make your repository stand out and grab the attention of the viewer. Remember, we’re targeting the Github browsers, not just the devs.
Here are some of the key points you have to consider when making a graphic. I’ll be using the RKNH graphic as the example.
Figure out how to communicate the purpose of your repo.
What will people relate to? You want people to understand why this repo might be useful. RKNH builds simple notification icons, so I decided to use Facebook’s notification center as the central image.
Plan the space of the graphic.
Title at the top with a custom bitly link, and twitter handle at the bottom. I have 2 boxes so I can plan for 2 graphics.
The left graphic is to show RKNH’s use. It’s centered with a lot of white space. Since most people read left to right, left should be the broad concept, right should be specifics.
The right graphic is also centered with a lot of white space. If the left is “what this is”, the right is “why you want to use this”. The animations are attractive, so I wanted to show them off.
The final result
The graphic is not just a kickass way to start a README, it’s also super shareable.
[Tools: Most of my design work is done in Bohemian Sketch 3, an absurdly simple graphic design app. GIFs are captured with LICEcap and edited with GIMP. They’re a little unwieldy, but they’re the best free solutions I’ve found.]
6. THE FEEDBACK LOOP
Iterate! Pivot! Actionable Metrics!
Now that you’ve got a graphic and some well-documented code, I’m going to show you how to play the system. I’ll start by explaining Github’s Trending mechanism.
This is the page you’re going to aim to be on. It’s the “today” page for trending repos in your language. If you get on this page, you will hopefully get on the “weekly” and then “monthly” pages. This happened for all five of my repos.
And this is why this matters. 90%+ of my view redirects come from Github, most likely from the trending page.
Thousands flock to the Github trending pages to see what’s up-and-coming in the dev world. These browsers are already logged into Github accounts, so if you’re going to get stars from anyone, it’s going to be from them.
Getting on the list is simply a matter of getting lots of stars within the designated time frame. If you nabbed more stars than project X in 24 hours, you’ll be higher on the “today” trending list. But X might have gotten more stars within 7 days than you, in that case they’ll be higher on the “weekly” trending list.
I’ve found that 30 stars is a good goal for iOS repos because it puts me in the top ten on “trending today”. The “feedback loop” is my method of engaging the audience by iterating on their suggestions as fast as I can. This is inspired by “The Lean Startup” and is how I get my first 30 stars.
The loop looks like this:
- Post a link of the graphic (more effective than the Github link)
- Get feedback within minutes
- Act on feedback within minutes, reply to feedback
- Repeat 2–4 until satisfied
Because people have been frustrated with me in the past, I’m weary of pubbing my work on social media. So aside from this article, you’ll rarely ever see my stuff on Facebook. For me, Reddit was a place where I found anonymous feedback from people that wanted to learn as well. It was a really positive and confidence-boosting environment.
Reddit doesn’t have to be your platform though. I just found that it fit me best for personal reasons. You might prefer Product Hunt, Twitter, colleagues, the local computer science club, or developer-focused Facebook groups. Make sure to keep these general rules in mind though:
- If your work is garbage, feedback will be garbage.
- If documentation is garbage, feedback will be nonexistent.
- If you’re a dick and argue with people who took the time to give you their opinions, expect to find it difficult to reach out to them again.
- If your post is blatantly self-promotional, it likely won’t get any good feedback (especially on reddit).
Let’s look at the Referring Sites screenshot again. It shows that Reddit sent me 58 users. I need to get 30 stars from 58 people. This just goes to show that while this might be my secret weapon, it’s not a sure thing. You still have to work hard to earn those stars.
If I think I’m right on the brink, sometimes I reach out to a few of my developer friends (shoutout to @JaredTMoskowitz, @charlieloumeyer, @ascrookes, StartupTheKid, @gwulfs, @marcella_h, and more) for some help. All of these guys kill it, so watch out for them.
Conclusion
To anyone who’s stuck with me this far, bravo! I hope you kill it and get millions of yellow pointy things on your projects. Keep in mind that this is not a magical solution. You still have to put in the work and this will take many hours. I’m not exaggerating when I talk about the 1:1 relationship between coding and readme hours. More complex projects need clearer documentation.
If you’re working on something cool, I’d love to see it! I’m at cwRichardKim@gmail.com or @cwRichardKim (Twitter, Github, LinkedIn). Send me friendvites, connects, follows, presents, Happy New Year!
Follow Up
Gerasimos Maropoulos very kindly allowed me to share his project, Iris which gained around 6,500 stars in 6 months. Bravo 👏👏👏
Next: read about how building a popular joke app taught me how broken the app store is:
