On December 27, 2024, I announced my open-source project, QuickSnip, on YouTube. First day was very quiet. And then suddenly, views started to increase. More and more people were watching, commenting and subscribing.
5 days in, and we're looking at 15k views with 1000 likes on YouTube and an incredible 200+ stars on GitHub.
So, I decided to share my journey about managing an open-source project with 50+ contributors and over 100 issues and pull requests in these 2 weeks.
Table of Contents
That's a lot of things xD
- README.md and CONTRIBUTING.md
- License
- Prettier
- Collaborators
- CODEOWNERS
- FUNDING
- Discord Server
- Issue Template
- Pull Request Template
- GitHub Actions
- Code of Conduct
- VISION
- Deployment
README.md and CONTRIBUTING.md
When working on an open-source project, README.md and CONTRIBUTING.md files are often overlooked. But, they're the only way contributors can understand what your project is about and how they can contribute.
These file explain your expectations for the community. Once you establish solid README.md and CONTRIBUTING.md files from the start, it will save you hours when dealing with pull requests. Trust me, this is from experience :)
License
Now, let's talk about legal side of open source. You might have already seen a LICENSE file in pretty much every open-source project, the most common being MIT License. Basically, if a project doesn't have a license, copyright laws kick in automatically. That means others can't use or modify your code, which defeats the whole spirit of encouraging people to use and contribute. That's why always add a license to keep things simple and legal for everyone.
Prettier
Everyone has their own coding style. But, in open-source projects, everyone should be on the same page. And, formatting tools like Prettier set a standard for code style.
As soon as pull requests started rolling in, an immediate issue was code formatting. We immediately created an issue for it and resolved it as quickly as possible.
Collaborators
One major lesson I learned is trust. As the project grew, managing it solo became overwhelming. When people were adding snippets to our database, I noticed a few people consistently reviewing others code and giving great feedback. So, I made them collaborators.
Now, our collaborators help merge pull requests, review issues, and keep things running. I just show them the path and let them lead. If you’re serious about scaling, learn to trust your community.
And, for personal public repo, like ours, only way to allow your trusted contributors to merge or reject pull requests is through giving them a collaborator role.
However, you are not able to assign roles or manage access for collaborators, which I learnt, is possible in organization repo - something we may consider to switch to at some point as we grow.
CODEOWNERS
When there's a pull request, it was difficult to know what was it about unless one of our collaborators reviewed it themselves. And, managing hundreds of them can be overwhelming.
After some research, I found that CODEOWNERS was a thing. Basically, it will let you assign specific contributors to different parts of your project. For example, we have 3 types of maintainers:
- Global maintainers, who are responsible for the full scope of the project.
- Code maintainers, who take care of bugs and new features.
- And, last but not least, snippet maintainers, who review snippet-related pull requests, and see whether it fits the scope of QuickSnip.
Now, with CODEOWNERS set up, it will automatically notifies the right maintainers when there's a pull request with a change on their assigned folders.
But, remember: maintainers need to have write access, so you need to make them collaborators first.
FUNDING
I was wondering how some repos had a sponsor button. After digging the settings for a while, I found that you need to create FUNDING.yml file under .github folder, in which you can add your any of your sponsor links. I added my Ko-fi link, and now you can support QuickSnip as well. It's not necessary, but always appreciated. :)
Discord server
As more and more people were suggesting new ideas and feature requests, we needed a better way of communication to discuss those ideas with our maintainers. One of our maintainers suggested Discord. Now, we have a QuickSnip Community server, where we discuss ideas and plans.
There's also GitHub Discussions we were experimenting with. But, more people were liking and joining Discord server. So, sorry GitHub Discussions.
Issue template
In open-source projects, it's easy to get lost in issues when you have to differentiate what is a bug, feature request or something unrelated.
So, I visited other open-source projects to get an idea on how they are managing their issues. And, I came across Developer Quiz Site from FreeCodeCamp. When I tried to create an issue and I saw this: 4 options to choose from:
- Bug report
- Documentation
- Feature request
- And, general
It was very clean and organized. After taking some inspirations, I implemented them in our own project.
Pull Request template
Now, PRs were next.
In our project, some pull requests didn't follow style guide or sometimes had no descriptions. It made it difficult for our maintainers to review the PRs.
And, to my luck, there were pull request templates as well. Thank you, GitHub. First, I gathered feedback from our maintainers what they would like to add in pull request template so it can save their time. Then, I created one. It contains the type of change, an important checklist, related issues and additional info.
Now, every PR is clear and consistent.
GitHub Actions
GitHub Actions feels like magic, but in reality, it's a really cool feature. QuickSnip now stores snippets as markdown files, but the frontend uses JSON to show them in the website. Manually converting markdown to JSON? No thanks.
We wrote a script in GitHub Actions and automated it. Now, whenever someone adds a new snippet, it converts the files automatically. I’ll talk more about this in my next video. Stay tuned!
Code of Conduct
Code of Conduct is often misunderstood on what it actually means. I’ll admit — I thought Code of Conduct was about style guides at first. Turns out, it’s a set of rules people should follow to create a welcoming environment.
Our community has been fantastic so far, and as we grow, a Code of Conduct will ensure we're always friendly and kind to each other.
VISION
As the project started to gain traction (which is awesome), a lot of ideas and feature requests began pouring in (which is even more awesome). But, the problem was it was easy to lose focus. We realized it was important to set the boundaries and understand the scope and future of QuickSnip.
Inspired from this article on contributing.md website, we created a file, called VISION.md, which outlines the goals, roadmap and the future of QuickSnip. While it outlines the current vision for QuickSnip, our proposed future plans may evolve based on community feedback and contributions. So, stay tuned for future updates! ;)
The main purpose of VISION.md file is stay focused on your goals. As the article puts it perfectly:
"As a new maintainer, one person narrates how he regrets steering away from his vision in the early stages of his project when he got his first feature request. He appreciates that a clear vision has kept him focused and helped him prioritize important requests."
Deployment
QuickSnip is hosted on Netlify, and here’s a surprise I didn’t see coming: build minutes.
Since the project is on Free plan, there's limit on build minutes, which is 300. Basically, it's about how many minutes it takes from loading your dependencies (all the code stuff) to deploying them to the site.
And, according to Netlify, each build takes around 2 minutes.
I didn't know about build minutes until I got an email notification from Netlify saying I had reached over 50% of build minutes. That is when I started to take action. I assume, what was happening was that Netlify was also counting build minutes for every PR request since it had to show deploy previews before PR is merged. So, I had to disable deploy previews.
Luckily, thanks to Netlify, build minutes are reset every month. I was so excited to find out about this. In our project, build minutes will reset on January 17, just one day after my birthday.
Outro
These past two weeks taught me more than an entire year. So, here's a small tip from my side:
Open-source is challenging, rewarding, and full of surprises. If you haven’t started an open-source project yet—do it now. You’ll grow, learn, and connect with amazing people.
As always, thanks for reading and I will see you in the next one.
Top comments (2)
Interesting read, I too have created my first npm package recently and found myself figuring all of this out also, and funny enough, it is my birthday tomorrow lol. I will be referring back to this later today to double check some things regarding the setup of it all, and, I hope you have a good birthday!
Thanks :) Happy birthday to you as well.