Last month my Wix open-source library, sentry-teskit, broke a record. It went over 240K downloads per month for the first time! However, having ~240K downloads a month wasn’t something that happened overnight.
There is a very challenging journey behind it. In this article, I’ll share how to stand out with a useful open source project and spread the word about it. I will also show tools I’ve used and how they helped along the way to make this library more community-oriented and allow more developers to use it and contribute to it.
Sentry
Sentry is a real-time code-crash and monitoring system tool which gives the development team full visibility into their code, so they can catch issues before they become a downtime. Sentry’s tools and solutions are trusted and used by 85K companies around the world, such as Disney, GitHub, Microsoft and, of course, Wix.
How It Started
It all began when I was given a development task. As part of testing it, I needed to write a generic module to intercept the error events sent to the monitoring system (in tests). When I searched for a solution, I was surprised that something so critical was missing. I even approached Sentry to check what their solution was for it, and they didn’t have such a testkit.
So I wrote my own testkit add-on. It wasn’t super complex, just a few lines of code and I had it. Then I thought, “why not publish as open source so others can use it?”.
Here’s my take on how it got to 220K downloads:
1. Being There First Is Not Enough As mentioned, thousands of downloads were not achieved overnight. So I wrote a few lines of code that solves the problem of working with Sentry in a development/testing environment, so what?
In order to even get started with spreading the word and suggest my library to other developers out there (either within my company or outside of Wix) - I had to write some guidelines of how to use it, from installation to usage examples, and even some caveats. So I started with a simple README file.
2. Speak Out, Listen to Feedback, and Cover More Cases Talk about it! Talk about it with everyone you meet. “Everyone” means not only techies. Talk about it with your significant other, your family or with your extended family. The fact that you talk about it with non-tech people makes you practice on how to pitch your idea and solution in a generic way and with simple explanations.
Yes - the main feedback you will get will be from your techie friends and colleagues. Ask them what they think about it.
Show them your code and get a code review. Ask them what they think of case X and whether this covers case Y, and if not, what should be done in order to get case Y covered as well → opening GitHub issues → inviting PRs.
3. I Let Sentry Know About It While looking for a solution, I was in close contact with Sentry R&D teams. I even contributed to their repositories. Luckily, all of their tools are open source on GitHub. So I had some leads and strings I could pull and say: “hey guys, what do you think of this…?”
I also got their feedback and their actual blessing of “yeah, we think it’s cool” and then they put a link in their official docs to this Sentry-Testkit with short explanations and a reference to my repository where all the guides are – This was the game changer move for this library. When a company like Sentry links your plugin in their official docs - it says A LOT!
4. Branding & Documentation Now it's official. You have a library that starts to get downloads. That’s great, but downloads means users, and that means humans are interacting with it. Whether it happens on a daily basis or once in a while - you will need to have 2 things:
A Logo - I used Wix’s Logo Maker tool to create the Sentry-Test Kits logo. I wanted something that would be inspired by Sentry’s logo so people can associate them with each other. I chose the pinkish coloring as this was the Pantone color of the year back in 2019. Using Wix’s Logo Maker also let me apply some customization over the logo itself. It also provided me with licensing for the fonts and covered everything in that regard.
Documentation website - The first thing mentioned above is the fact that any library, in order for people to use it, has to be well documented. As time went by, the library (and community) grew more and more. It needed a proper documentation site to provide an easy way to start using the library, an easy way to document and explain all the functions, APIs, and best practices of this library. To generate a professional documentation site, I looked for tools that support Github Pages out-of-the-box. Github Pages is a very flexible and convenient way to deploy a documentation site. At first, I was using Docsify, which was very easy and super fast to generate a documentation site which is based only on Markdown (*.md) files. Recently, Sentry-Testkit’s documentation site has been upgraded significantly and I am now using Docusaurus. It’s a well known tool in many open source software (OSS) projects and it gives a lot of great stuff out-of-the-box like search engine integration, better SEO visibility, Google Analytics integration, and more content customization (it supports React component rendering, etc.). When you have your own docs site, you can even use it for more stuff like sharing technical blog posts related to the library or the domain, or sharing other best practices for non-common use cases, etc.
5. Be Responsive With Issues and Embrace PRs
As the library becomes more and more popular, developers will open issues for you on the GitHub issues page. Some of those issues are bugs, feature requests, calling for help and support, etc. This is YOUR community. You need to treat it respectfully and “listen” carefully to what they say. Not that they are always right, but listening to feedback is always a good thing to do. Also, as mentioned above, it leads to contributions.
Pull requests (PRs) are one of the most exciting things happening in your library. When another developer who you’ve never met contributes to your library, it means not only that they are users, but they actually take an action to be part of your community and be involved in the overall solution your library provides.
Yes, there were some PRs that I’ve reviewed and it was hard to follow the suggested code, or I wasn't sure why it was even needed or whether I wanted to support such a scenario… every PR has many implications from the moment it is merged and further on.
So, it’s really important to pay attention to all the details and give your respective feedback, as well.
6. Maintain Stability and Follow OSS Conventions Developers are not a crowd that looks for surprises (usually :) ). One of the ways to not surprise your users is to follow simple OSS conventions, such as maintaining versions according to “semver” convention, maintain a constantly updated CHANGELOG file, and last but not least - having tests over every functionality your library provides. I’m not getting into the discussion of “TDD…” and so on… Testing is super important because this is the only way you can make sure that for every tiny change, the entire library can be tested for not breaking things up. Yes, we are all humans and sometimes bad, unpredictable things happen. Nevertheless, do whatever you can to prevent it from failing - write a test and guarantee no regression occurs with every release.
Conclusion
Maintaining an open source library is a job, a very enjoyable one. It’s a job you need to be committed to for it to grow a community around it. I’ll summarize the gist of the above in 3 main points:
Documentation - this is your open source gateway. It doesn’t matter if it’s a tool, an algorithm or something you’re doing for fun. A documentation site is a must for the dev community to interact with your open source project.
Responsiveness - respond to people who are engaging with your open source. They’re either using Github issues, Stackoverflow, or contacting you directly by email or on social media.
Approach key factors that are relevant to your open source project. When a known company or people are using your open source, it will make it more trustworthy by others, as well.
This post was written by Ziv Levy
You can follow him on Twitter
For more engineering updates and insights:
Join our Telegram channel
Visit us on GitHub
Subscribe to our YouTube channel