I've published a number of Open Source Python libraries, but none have seen as much buzz as Rich. Released in 2020, the Rich repo has 35,000 stars on Github. Since then I've released Textual (a work in progress) and Rich-CLI, both of which are on a similar trajectory as far as GitHub stars go.

In this post I'd like to lay out what I think contributed to the popularity of Rich, which you can hopefully apply to your own open source project(s).

Should I promote my project?

Should you promote your project at all? Until the word is out, your public repository on Github is essentially private through obscurity. The might be fine if your code is for your own use, but there can be significant benefits to increasing the visibility of your work. Before I discuss the benefits I want to first cover potential downsides of promoting your work.

The first downside is issues as received through the GitHub issues tab. Note that I didn't say bug reports, which should be welcomed. Many issues are feature requests. Somebody liked your work enough to request an addition to it or an expansion of the scope of your project. Good idea or not, you may feel a sense of obligation to give people what they are asking for (even if you have no need of it yourself). If your project is popular enough, the volume of feature requests can exceed whatever time you have to work on it. This is a recipe for maintainer burnout and the temptation to rage quit and walk away is real.

via GIPHY

The next downside of a popular repo is that you will take on a responsibility not to break other projects. You will find yourself balancing new features and bug fixes while thinking about the numerous ways your changes could ruin some other maintainer's day. You've lost the creative freedom you had after typing git init at the command prompt. You started as emperor of your own realm of code and ended up with a hundred new bosses.

If this sounds like gatekeeping, let me offset that by saying that raising awareness of your personal brand (or your company) can help you with getting a job, promoting a service, making professional connections, and more. My personal experience is that my pet projects set me on a path to founding textualize.io. So no gatekeeping. Promoting your work is a good idea on so many levels, and there is nothing preventing you from going down that route.

When should I announce my project?

If you wait until your application or library is feature complete, optimized to the nth degree, and bug free (if that is possible) then you've missed out on building a lot of potential interest in your project. If you have a one line README and a LICENSE file in your GitHub repository then that may be too early to promote it. The sweet-spot is probably closer to the one-line readme than the finished product.

I would say that the ideal point to focus on building an audience for your work is when you have something tangible to try out. It doesn't need to have all the features you are aiming for: one core feature is enough. At this point you aren't asking people to adopt your project and start actively using it. You only need enough to pique their interest.

More important than features is a README. This is what people will see when they visit your repo. Summarize what your project does in the first paragraph (ideally sentence), let them know how to get started, show them working examples of code and equally importantly, show them the results. If it makes sense, add some screenshots. Better still, add a video or gif.

Building in public

For some projects it may makes sense to start generating interest even earlier. If you embrace Twitter, or whatever the kids are using these days, you can post about progress with your project before you have a working prototype.

It makes sense to do this throughout as you develop your project. It may seem like you're shouting in to the ether for a while, but people will pick up on your enthusiasm and share in your passion. Post ideas, questions, take polls, and share code snippets while actively working on your project to build an audience. The feedback you get from building in public can be incredibly valuable.

There isn't a great deal of code you can squeeze in to Twitter's 280 character limit, so you might want to post some images of code. I can recommend carbon.now.sh and snappify.io, both of which are excellent. Although if you expect people to try the code out, you may want to also post a gist for cut 'n' pastablility.

Where should I announce my project?

Once you have your core feature and a decent README you should consider posting it somewhere to gain visibility. If there is a forum you visit that is relevant to your project you should probably begin by posting it there, but the two main outlets I've found for announcing your project are Reddit and Hacker News.

For Reddit you should pick a sub-Reddit that is relevant to your project, for Python modules /r/python is likely a good choice but there may be more apt subreddit(s) for your project. Be sure to post with a title that describes your project well. Unless you are extremely good at playing the social media game I'd avoid any title that looks click-baity. Add a nice description of your project in a comment and stick around for the replies.

Hacker News is similar. If you are announcing your project, consider posting it to Show HN which is specifically for promoting something you have worked on. It's a much smaller pool of posts than regular posts and your chances of getting to the front page are much higher. Like Reddit, avoid the click-baity titles, and stick around to reply to comments.

If all goes well your project will be on the front page for a few hours or possibly more than a day. Your repo will see some traffic and you'll gain stars. You'll also get some feedback which can benefit your project.

Posting to social media is not without risks. You may receive criticism of your project, your code, or even the core idea. Try to take those on-board, there may be some justified criticisms there. Feel free to present your viewpoint in response, but don't be tempted to change anybody's mind. Always take the high-ground and agree to disagree, otherwise you may be drawn in to a good old fashioned flame war, and nobody wins.

via GIPHY

Keeping the ball rolling

If your announcement goes well, you will have a few GitHub stars, and some people willing to follow along with your work. Keep that momentum going by talking about your work. You don't need to wait until you have a new version.

Twitter is a great medium for this. Post about your thoughts on the software development process. Ask questions, get feedback. Keep it light-hearted and self-deprecating. You might find it easy to post about your successes; a bug you fixed, or a feature you implemented, but your failures can be equally interesting as content. Recognizing a design flaw in your code and having to back out of a week or two work can be as much of a learning exercise for others as it is yourself. If you can talk about that with humor, others will want to follow along.

From time to time you will have new features or other milestones that may be worth publicizing. You can do this in a blogpost which you can then post to the usual social media channels (Reddit, Hacker News and others). Give your post as much attention as your original announcement. Be sure to add as much relevant content as you can plus screenshots / gifs if you have them. Avoid simple "new version" announcements.

Be aware though that there is a large element of luck in social media. Don't let it get you down if your post doesn't get much traction and ends up buried. Wait a couple of weeks and try again. Be sure to familiarize yourself with the site's policies on self promotion and posting frequency. Building an audience can take time, you don't want your content to be labelled as spam by trying too hard.

Issue driven development

I mentioned that feature requests can be hard to manage, and you may have to develop polite ways saying no to new features. However feature requests should probably drive the development of your application / API once you have the core set of features you originally intended. If the same feature comes up multiple times, that may be a good indication that it would be worth focusing your time there. Similarly if many people struggle with the same part of your API or piece of functionality, it could indicate you need to re-think something. This is still true even if you believe the user is doing it wrong. Finding the source of the confusion replacing it with something more intuitive will lead to a better API.

It may feel like you are losing control over something you created. But try not to think of it that way. Ultimately your code is not a work of art to be admired, it is a product. And like all products it will have consumers. Building something which makes their lives easier is how your product becomes successful.