Open Source Reflections - 1 Year, 1k Stars, and 130K Downloads Later

Introduction

A little over a year ago, I started programming FastCRUD - Robust CRUD Operations and Flexible Endpoint Creation for FastAPI, my open source project.

It wasn’t the first open source project I created, nor was it my first library, but certainly some interesting changes happened in my thinking about how to approach projects since then. The idea here is to talk a bit about these reflections and the lessons I’ve learned, and perhaps get more of you interested in open source.

The general idea is to discuss how to create a successful open source project.

TL;DR:

Make something useful for yourself
Don’t start with “what to do,” start with “why do it”
Make the simplest possible thing that solves the problem
Documentation, documentation, documentation
Get some social proof
Promote your project
Take criticism
Maintain your project
Know how to ask for help

Context

I used to work primarily with data, going from Data Analyst to Analytics Engineer and Data Engineer, even deploying Machine Learning models, but I confess I really missed programming.

The truth is that when working with data, you don’t program as much, and when you do, it’s not that interesting. It’s mostly data pipelines, transformations (in SQL or Python), eventually some predictive modeling or machine learning deployment, but the programming part of these problems is kind of already solved. What really generates value in these things - unless you’re in huge companies where infrastructure matters a lot - is much more about understanding the business, optimizing queries, knowing how to answer questions (and which questions people are really asking), and eventually this becomes somewhat repetitive.

Missing my programming days from college and my (failed) startups, I decided to start creating open source projects to satisfy this craving.

What Makes a Successful Project?

Well, to start talking about how to succeed in a project, it’s important to define what success is. The truth is that this varies quite a bit, but after some time I moved my definition of success from “people seeing, using, starring” to “it’s useful to me.”

The only thing you can control about the project is whether it will be useful to you, not whether others will like it or whether it will be useful to them. If these things happen, great, but the reality is that after a while, you value these vanity metrics less.

Of course, this changes depending on your goal. If you’re doing the project to improve your portfolio, you’ll want to use relevant technologies for that and want it to have more visibility. Either way, take the maxim “will this be useful to me?” to heart. In the worst-case scenario, you haven’t wasted your time (beyond the learning).

Perhaps you’ll discover that for your specific problem, it’s better to contribute to an existing project than to make your own.

How to Come Up with Project Ideas?

Here we have another maxim: don’t start with “what to do,” start with “why do it.” There’s no way to make something useful for you (and, maybe, for others) without some domain knowledge. The most important thing is to know what problems exist in the area.

Practical example:

I needed to improve on deploying machine learning models for work, so I decided to learn FastAPI
After using FastAPI for a while, I saw that many things didn’t have a standard way of doing them, so I decided to create a template for myself to facilitate creating APIs with the technologies I liked
I discovered there was no admin panel for FastAPI the way I liked, so I decided to create one (for me to use)
To create this panel, I needed an easy way to generate CRUD and endpoints from SQLAlchemy models and Pydantic schemas, so I created FastCRUD to make my work easier

Notice how every project here had a natural motivation before? Some problem I needed to solve for myself (or for the company I worked for). Precisely because of this, even if no one had seen or used the projects, it would still have been a success for me.

As a bonus, if these projects solve a problem for me, the chance they solve problems for other people is greater (as was the case).

The general idea here is to start by thinking about solving a problem, not creating a project. Maybe you don’t know what that problem is yet, so before that, go study, explore, experience it firsthand.

How to Develop?

Now that you know what to do (and more importantly, why do it), you will actually start developing. The maxim of this section is very simple: make the simplest possible thing that solves the problem.

Start small, remember that your initial goal is to solve the problem, not to make the prettiest thing possible. Once you have an initial solution, you can add things and refactor (when relevant).

Practical example:

I wanted an easier way to filter for my admin panel, so I added django-style ORM filters to FastCRUD
People started asking for SQLModel support, so I added it
I was tired of reimplementing pagination every time, so I created utils for this in FastCRUD

An interesting thing is that at this point, people started finding it useful and using it, so they identified problems, started asking for things, and even contributing by opening pull requests.

It’s important to talk about how people found out about my project, which brings us to the next part.

How to Promote Your Project?

Here things start to get more political. Although our initial definition of a successful open source project was something useful to ourselves, the truth is that the more people contributing, the better.

You probably won’t find all the bugs alone, won’t think of all the improvements on your own, and will also learn more slowly without other people stressing your idea.

What I learned (after getting beaten up a lot) is:

Documentation, documentation, documentation. A useful README about what the project is and how to use it is the minimum. The more you make it easier for others to understand things, the more likely they are to help. Get inspired by documentation you like, write, write, write.
Get about 10-20 stars before promoting. This is sad, but if you don’t ask for initial stars from friends, no one will look at your project. The idea isn’t even to gain stars after that, but people won’t look and take it seriously without some social validation. If you don’t have many friends to try out your project, it’s okay to promote without this.
Promote. It might seem obvious, but people are often afraid of this. The sooner you lose the fear of showing things (which certainly won’t be perfect), the better. Post here, on LinkedIn, on Reddit (without emojis, they hate them) and expect criticism, praise, tips. Don’t be annoying, don’t keep promoting all the time.
Take criticism. People will speak ill, it’s normal. Evaluate what is useful to you and improve, ignore what isn’t useful.