Open-source launch checklist: 12 steps before and after you post
By Bright Oparaji9 min read
Promotion that works looks a lot like product work: find the people with the problem, make the project easy to judge, show up where they are, listen, and improve.
This is the working version of our guide to promoting an open-source project: the same approach, laid out as twelve steps you can tick off, with examples of messages that work and ones that do not. Two free tools do part of the work. The README quality checker scores your README and lists what to fix, and the open-source launch planner turns your project's details into a checklist and a shortlist of communities.
Step 1: Define the target audience
Write one sentence naming the person who needs your project, the situation they are in and what they do today instead.
- Weak: "For developers."
- Better: "For backend developers running Postgres in production who need schema changes without downtime, and who currently write migration scripts by hand."
Everything later depends on this. It tells you which communities to visit, what to say there and which feedback to take seriously. If you cannot write the sentence, talk to three people who use the project, or would, before doing anything else.
Step 2: Clarify the value proposition
Turn the audience sentence into a claim a reader can check in seconds: what the project does, for whom, and how it differs from the usual alternative.
A useful template:
For [audience] who [situation], [project] [does what]. Unlike [usual alternative], it [one difference that matters to them].
Keep the difference specific and verifiable. "Faster" invites the question "than what, measured how?" "Applies schema changes without locking tables, so writes continue during a migration" answers it.
Step 3: Improve the README
Every post you make sends people to the README, and most of them decide within the first screen whether to stay. Before promoting anything, make sure the top of the README:
- says what the project is in one plain sentence, above badges and logos
- says who it is for
- shows installation and a minimal working example
- shows the project, with a screenshot, a recording or example output
Our guide to improving a GitHub README has before-and-after examples, and the README quality checker will tell you which of these yours is missing.
Step 4: Prepare demonstrations
People believe what they can see. Prepare one or more of:
- a screenshot or short recording of the project doing its main job
- a terminal session showing a real command and its output
- a live demo or playground, if the project can run in a browser
- a before-and-after code sample, for a library
Keep it honest. Show a real result, not an idealised mock-up, and note anything that needs setup the demo hides.
Step 5: Identify suitable communities
List places where the people from step 1 already discuss the problem: the forum or chat of the language or framework you build on, topic communities, newsletters, question sites. Prefer specific over large. Our comparison of the best communities for open-source projects covers the common options and how to judge fit.
Aim for a shortlist of two or three for launch and a few more for the weeks after.
Step 6: Study community rules
For each community on the shortlist, read the current rules and a week of recent posts before writing anything. Note:
- whether project posts are allowed, and where (some use a dedicated channel, flair or day)
- account requirements, such as age or prior participation
- which posts got thoughtful replies and which were ignored or removed
If a community does not allow promotion but fits your project perfectly, the instruction is to take part rather than post: answer questions there, and mention your project only where it genuinely answers one. The promotion guide links each major venue to its own rules, and Hacker News has a launch guide of its own.
Step 7: Write useful, audience-specific posts
Write a separate post for each community, in its own format and vocabulary. Lead with the problem, not the project.
An ineffective post:
Check out my new project! It's a blazing fast, modern, next-generation tool for developers. Please star it on GitHub! [link]
It says nothing a reader can check, is aimed at nobody, and asks for a favour instead of offering anything.
An effective post:
Schema migrations on our Postgres database kept locking busy tables, so I wrote a small tool that applies changes in batches and keeps writes flowing. It handles adding columns, indexes and constraints; it does not handle renames yet. Repository and a two-minute demo are here: [link]. I'd especially like to hear from anyone who has run migrations on tables over 100 GB: what broke for you?
It names the problem, says what the tool does and does not do, shows evidence, and asks a question the audience can answer.
Step 8: Publish thoughtfully
- Post to one community at a time, best fit first.
- Choose a time when you can stay for several hours to reply.
- Do not ask anyone to upvote, and do not coordinate votes. Most communities forbid it and many detect it.
- Spread the rest of your shortlist over the following weeks rather than posting everywhere on the same day.
Step 9: Respond to feedback
The replies are the most valuable part of a launch. Answer every question in the thread where it was asked. Thank people for bug reports and fix the serious ones quickly; replying "fixed in version 1.2.1" in the original thread shows the project is alive.
Treat criticism as information. If several people say the installation failed or the purpose was unclear, that is the next thing to fix, more than any feature request.
Step 10: Measure meaningful outcomes
Decide before launch what you will look at, and record numbers beforehand so you can compare: did my launch post work? explains why four weeks of history beats one. (For a weekly record you can keep going after launch, see how to measure open-source adoption.) A useful starting set:
| What to measure | Why | Where to find it |
|---|---|---|
| Visitors and referring sites | Shows which posts actually sent people | GitHub Insights, Traffic (keeps 14 days, so record it weekly) |
| Installs or downloads | Closer to use than stars | Your package registry or release downloads |
| Issues and discussions from new people | Someone tried it | Issue tracker, Discussions |
| Documentation visits | Serious evaluation | Your docs site analytics |
| Stars | Attention, as a trend | The repository page |
Our article on GitHub stars vs active users explains what each of these can and cannot tell you.
Step 11: Improve the project based on feedback
Sort what you heard into themes: installation problems, unclear purpose, missing features, bugs. Fix the themes that stop people getting started before the ones that would please existing users. Update the README with the answers to questions people asked more than once.
Each improvement is also a reason to post again later: a release that fixes what the first readers struggled with is a better story than the launch was.
Step 12: Build a repeatable distribution process
Promotion is not one launch day. Make it a routine tied to the work you already do:
- every release gets notes written for users, and a post in the one or two most relevant places
- every recurring question becomes a README section or a documentation page
- every month, check the measurements from step 10 and note what changed
- keep a simple log of what you posted, where, and what came of it
This is the part that makes the difference over a year, and the part that is easiest to let slide.
Common mistakes
| Mistake | Why it hurts | Instead |
|---|---|---|
| Posting before the README is ready | Visitors leave and rarely return | Finish steps 1 to 4 first |
| Posting the same text everywhere | Fits no audience; looks like spam | Write each post for its community |
| Asking for stars or upvotes | Against most community rules and easy to detect | Ask a question people can answer |
| Measuring success by stars alone | Rewards attention, not use | Track installs, referrers and questions from new people |
| Disappearing after posting | Unanswered questions read as an abandoned project | Post only when you can stay to reply |
| Exaggerating | Experienced readers test the claims | State what it does, and what it does not do yet |
Launch preparation checklist
- One sentence naming who the project is for
- A value proposition with one specific, checkable difference
- README explains the project above the fold, with install steps and an example
- A screenshot, recording or demo
- Installation tested on a clean machine by someone who has not seen the project
- Licence named in the README, and a contributing section
- A tagged release with notes
- Shortlist of two or three communities, with their current rules read
- A separate post drafted for each
- A week of baseline measurements recorded
- Time set aside to answer replies on launch day
A channel selection framework
For each candidate community, score three things from 0 to 2:
- Problem fit. Do people there discuss the problem your project solves? (0 never, 1 sometimes, 2 often)
- Use fit. Could they use what you built today? (0 no, 1 some of them, 2 most of them)
- Rules fit. Do the current rules allow your post in some form? (0 no, 1 with conditions you can meet, 2 yes)
Launch where the total is 5 or 6. Come back later to the 4s. A zero on rules means take part there instead of posting your project.
Practical next steps
- Write the audience sentence from step 1.
- Run your repository through the README quality checker and fix the top three recommendations.
- Use the launch planner to draft your shortlist, checklist and post outlines.
- Read the rules of your top two communities and draft one post for each.
If you would rather have this kept running across releases, Orviqa reads your repository, finds the communities that fit, drafts each post for your approval and checks your accounts before anything goes out. Nothing is published without your approval.