Ready to open-source your project? Here’s what you need to do first in order to keep your users safe and your contributors happy.
Table of Contents
✍️ Document
🪧 Share
🧹 Cleanup the Repo
Cleanup sensitive git commits
You’ve probably committed sensitive information that you don’t want others to see (e.g. passwords, API secrets, emails).
d258db5 fix: updated DB pw to: SQL_Kiddie_16
Not sure? Try running these commands from the root of your project, replacing YOUR_SECRET with any sensitive text you’re aware of.
# Search your git history to see where you
# messed up.
# If either of these give you output,
# you've got a problem.
git grep 'YOUR_SECRET' $(git rev-list --all)
git log -S "YOUR_SECRET" --oneline --name-only --pretty=format:"%h %s"
The easiest way to fix this is to remove any secrets from your HEAD and create a new repo. The downside of this approach is that you lose all your commit history, which makes your code harder to understand for newcomers.
If you’re willing to do some extra work to preserve your commit history, I recommend using BFG Repo Cleaner, a tool that removes sensitive files and blobs. Check out my tutorial here.
Remove large files from git
If you accidentally committed large files like build artifacts, you’re gonna discourage potential contributors by making it slower to clone, push, and pull your repository.
You can use BFG or git-filter-branch to remove those large files from your history.
# removing large files from git history using BFG:
java -jar bfg.jar --strip-blobs-bigger-than 100M some-big-repo.git
Prevent secrets and large files
Setup precommit hooks and secrets to prevent yourself and others from messing up. Here's an overview using husty and git-secrets.
Reduce commits
When solo hacking on a project, it doesn’t matter whether your commits are semantic, modular, or appropriate
When collaborating with other developers, however, the commit history’s readability affects your potential support.
Use git wizardry (rebase, squash, merge) to make it easier to read through the git log. Assuming you've been working on the project alone, consider squashing as many commits as possible and updating the git history on origin with git push --force.
See this video to find out which combo of pain is right for you:
Remove unused code
This includes TODO tests stubs, stale branches, functions that are never called, and unnecessary comments.
These smells helped you get up-to-speed when revisiting a section of the codebase, but they’ll slow everyone else down and make them trust your source code less.
That half-implemented code might be useful eventually, though, so remove it in a separate commit and save a link to that commit so you can reference it in the future. (Be careful not to squash that commit in the future step)
Fix CI
If you have broken tests, try to fix them. If that’s too much work, remove them and make an issue to fix them.
Add a badge to the README that shows the status of the CI tests on main.
Create an official release
If your project uses releases (e.g. libraries or mobile apps), create a new version.
When you do a new version tag, use the "generate release notes", it will automatically put the author of each PR as a tag in the notes list.
Fix security vulnerabilities
Releasing your code increases your attack surface, so patch any vulnerabilities, starting with those listed in GitHub’s Security alerts tab.
Mention in the README how to you’d like contributors to disclose any vulnerabilities they find. Make it easy for them to contact you directly (rather than opening a public issue).
Update dependencies
Get ahead of the inevitable dependency updates by enabling GitHub dependabot, which will autogenerate and tests dependency update PRs.
✍️ Document
Add a LICENSE
Choose a license. I prefer MIT, because it’s short and clear.
Add the license to your repo.
Update README.md
The quality of this file affects how well you convert users and contributors, so don’t cut corners here.
Include proper markdown formatting, reasonable titles, links, badges, and a table of contents.
Set your project apart by also adding GIFs and images. These visuals are important if you don’t have a landing page because they quickly show what problem your project solves and how it works.
While you shouldn’t breeze through this step, don’t go overboard by cramming too much information into this file.
The purpose of the README is to explain the problem your project addresses and how it solves it while making it easy for people to dive deeper by linking other resources.
Add CONTRIBUTING.md and CODE_OF_CONDUCT.md
Having these files signals that your project is alive and open for contributions (rather than an outdated portfolio piece).
No need to innovate here — find a template and adapt anything you need. See CONTRIBUTING.md examples and this CODE_OF_CONDUCT.md example.
Write Docs
The gap between your knowledge about the project and what’s documented determines how likely others will contribute.
If your README is the Instagram-able picture of your favorite dessert, your docs are the detailed recipe.
The docs explain how to install, run, debug, test, build, deploy, and troubleshoot your code.
Unless your project is extremely simple, separate these detailed instructions from the README.
Try GitHub’s Wiki Pages feature if you need a lightweight option (free for public repos).
If you’re keen to make reading your docs a great experience, create a dedicated static site for them. Here are some good options:
GitHub Pages
Cloudflare Pages
Read The Docs
MKDocs
Docusaurus (what I use at docs.compasscalendar.com)
Don’t forget, with great fanciness comes great complexity: webhooks, another repo, more markdown files, versioning, auto-deploying, SEO — all that stuff.
Worth it? Probs.
Finally, link a public Postman collection in your docs if your project includes an API (some examples).
Create Issue Templates
Issue templates prompt contributors to follow your organization structure by including default tags and fields. They add a little friction for contributors to open an issue, but they also ensure that:
the issues are high quality
you won’t keep re-answering the same questions
issues are handled consistently
GitHub comes with pre-defined templates — start by enabling those and customize as needed.
Create a roadmap
Use GitHub's milestone feature to set the roadmap for the near future of the app.
Write issues as descriptively as possible, citing filenames, specific behaviors, and how a contributor can know that they've successfully done the issue. Assign these to the appropriate milestones.
Try to keep the issues focused on single iterative changes. If there needs to be an epic issue, mark it as such and assign it to yourself (or a maintainer) and create a list of linked issues that will satisfy it. If it's a very big epic, just make it a milestone (easier to track)
Rename every PR so that it is descriptive about what it is actually doing.
Manual Test
The code is clean, the docs are written. It’s time to follow your recipe and eat it before telling others how great it is.
From a clean environment, clone/fork the code and do everything your docs explain. Fix or document every hiccup.
🪧 Share
It passes the taste test. Time to let the internet know.
For us developers, this is often the hardest part. We think promoting our work is unnecessary, scary, lame. Only those cringey marketing people do that stuff.
"Won’t it grow organically?" Probably not.
Best case scenario: someone stumbles upon your GitHub project after they look you up, find your pinned repo, skim the README, realize they happen to be the target user, install your code, try it, love it, share it for you on X and Reddit.
Most likely scenario: A few people stumble upon it, but no one actually tries or shares it. You lose motivation until the project fades into irrelevance.
Think of sharing your project as a win-win: your target user learns about a viable solution to their problem and you get feedback.
This feedback and attention helps your product and career, as I explain in my YouTube video, Why You Should Open-source 95% of Your Code:
Direct
Now that my pep talk is over, here’s how to share your project.
Text/email/DM people whose feedback is relevant to the project:
Peers who would be the target user
Mods of a subreddit you’d like to post on
People who have launched stuff and have the guts to point out where you’re wrong
If you can get them on a call, do that so you can gauge their reaction to the pitch.
If not, include the 1-3 sentence pitch, send them to the landing page / GitHub, and ask them to share feedback on the product and how you could improve my messaging.
If you can’t get enough target users to give you feedback, book some calls on LunchClub, a platform that sets up 1:1 casual convos for professionals. LunchClub people are strangers, so they don’t have the social pressure to gas you up as your network will.
This direct outreach is more work than just posting on social, but the feedback is quality and quick, which helps you improve your messaging before the next step.
Indirect
Share your project in places where your target user spends time. Some ideas:
r/opensource
r/roastmystartup
r/JavaScript | r/React
r/alphaandbetausers
r/startups
IndieHackers
FB Groups
Discord servers
Slack channels
Then share on more generic places:
X
Instagram
Threads
TikTok
10words
BetaList
Product Hunt
Analyze
Look back at your analytics to learn where your traffic came from so you can know where to focus in the future.
I was surprised to find that 75% of my impressions came from the r/opensource subreddit. Good to know!
🎉 Celebrate
You made something that solved your problem. You packaged it, deployed it, fixed lots of bugs, and kept iterating. Then you polished everything and made it public. You didn’t get distracted or give up along the way. Now people can use your work in their projects and do more cool stuff.
That’s badass!
Take some time to appreciate that.
Cheers 🥂
If you’re looking for a new open-source project and enjoy software that saves people time, consider checking out Compass on GitHub. I’d love to work with you.
Thanks for feedback from armahillo
Will steal some ideas form this ;) Thanks for the video on YouTube!