There's a moment every developer knows — you've been building something for weeks, you think it's finally good enough, and you push it public.
You write a README. You post it somewhere. You refresh the page.
Nothing.
No stars. No issues. No forks. Just your code, sitting in the open, completely ignored by the internet.
This is the normal experience of shipping open source. Nobody warns you about it, and it's worth talking about honestly.
The Romanticized Version vs. Reality
The version you see on Twitter:
Developer ships a tool over a weekend
Posts on Hacker News
Wakes up to 2,000 GitHub stars and a job offer
The version most people actually live:
Developer ships a tool after months of work
Posts on Hacker News, gets 3 upvotes (one is their roommate)
Checks analytics for two weeks, slowly stops checking
Moves on or quietly keeps building
Both are real. The first version just gets screenshotted more.
What "Shipped" Actually Means
Pushing code to GitHub is not shipping. It is a necessary precondition for shipping, but it is not the thing itself.
Shipping means:
Someone who doesn't know you can find it
Someone who doesn't know you can understand it in 60 seconds
Someone who doesn't know you can run it without asking you anything
Someone who doesn't know you wants to tell someone else about it
Most first open source projects fail the second test. The README is written for the person who built it, not the person discovering it for the first time.
The README Is the Product (At First)
Before anyone runs your code, they read your README. And they make a decision in about 30 seconds.
A README that converts has:
One sentence that says exactly what it does — not what category it's in, not what tech it uses. What it does.
A quick demo — a GIF, a screenshot, a code snippet. Something visual.
A getting started section that actually works — copy-paste commands, no assumptions about what's already installed.
Why this, not something else — if a similar tool exists, say what's different. If nothing similar exists, say that.
What kills a README:
❌ "A powerful, flexible, extensible framework for..."
❌ Installation instructions that skip three assumed steps
❌ No screenshot or demo
❌ A features list with no context for why those features matter
Your README is a cold email to a stranger. Write it like one.
Distribution Is a Separate Skill
Code quality and discoverability are completely unrelated axes.
Some of the most-starred repos on GitHub are not the best implementations of their idea. They're the ones that got posted at the right time, on the right platform, with the right framing.
This is not cynical — it's just how distribution works. The best tool that nobody finds helps nobody.
Places that actually move the needle for open source:
Platform
Best for
Hacker News (Show HN)
Developer tools, infra, anything technical
Reddit (r/programming, niche subs)
Language-specific or domain-specific tools
Dev.to / Hashnode
Tutorials that introduce your project naturally
Twitter/X threads
Building in public, before-and-after comparisons
Discord / Slack communities
Niche tools with a specific target community
The pattern that works best: write something useful about the problem your project solves, then mention the project. Not the other way around.
Your First Users Will Find Bugs You Never Imagined
When someone other than you runs your code for the first time, one of two things happens:
It works, and you feel briefly invincible
It breaks in a way you never considered, and you learn something real
The second outcome is more common and more valuable. Real users have different operating systems, different versions, different assumptions about how tools should behave.
When the first issue gets filed, resist the urge to be defensive. That person just did you a favor. They cared enough to tell you instead of quietly uninstalling.
The first issue on your repo is a milestone, not a problem.
The Maintenance Reality
Open source doesn't end at launch. If the project gets any traction, it becomes a responsibility:
Issues pile up, some reasonable, some not
PRs arrive with different code styles and different assumptions
People ask for features that would break the thing you were trying to build
Keeping dependencies updated is its own part-time job
This is worth knowing before you start. Not to discourage — but because choosing a license, setting expectations in your README, and deciding how much support you'll offer are real decisions that affect your life later.
A good CONTRIBUTING.md and a clear scope statement in your README saves you hours of uncomfortable issue thread conversations.
What It's Actually Worth
Here's the honest answer to "why bother?"
You will learn more from one real user filing an issue than from a hundred hours of solo building. The feedback loop is different when stakes are real.
A public repo with usage is a portfolio piece that no interview question can replicate. It shows taste, follow-through, and the ability to communicate technically.
The compounding is real but slow. Most repos that matter now were ignored for their first year.
You might actually help someone. This sounds obvious but it's easy to lose sight of — there is a developer somewhere with your exact problem who will find your solution and quietly thank you by starring it at 2am.
The One Thing
If you take one thing from this:
Ship it before it's ready, document it like it's already being used by strangers, and post it in one specific place where your exact user already hangs out.
The rest is iteration.