Launch guideDeveloper tools
How to launch an open-source project
An open-source launch is judged in the first 30 seconds on GitHub: does the README say what it is, show it working and tell me how to install it? Stars follow from that, not from posting everywhere. The durable traffic comes from docs pages that answer the exact problems people search, and from being linked in the lists and discussions developers already trust.
Updated · platform facts checked against the official docs linked below
At a glance
Where people find open-source projects
- Hacker News (Show HN): The classic launch for open-source tools; the audience installs and reads code.
- GitHub topics and Explore: Topics put the repo on topic pages people browse.
- Awesome lists: Curated lists per language or domain; each has its own contribution rules.
- Language and framework communities: Subreddits, Discords and newsletters for the ecosystem your project serves.
- LaunchRanked: A permanent project page linking to the repo and docs.
Assets to prepare
| Asset | Spec or guidance |
|---|---|
| README | One-line description, a GIF or code sample, install command, quick start, license, contributing link. |
| Social preview image | At least 640×320, 1280×640 for best display; PNG, JPG or GIF under 1 MB.[1] |
| Topics | Up to 20; lowercase letters, numbers and hyphens.[2] |
| License, CONTRIBUTING and CODE_OF_CONDUCT | People check the license before they adopt anything. |
| First tagged release | A GitHub Release with notes so people can pin a version. |
| Docs site | Even a single page on your own domain, so docs can rank. |
Store and listing rules
What the platform itself says, with a link to the page we checked.
- Show HN: you must have made it, people must be able to try it, and don't ask friends to upvote or comment.[3]
- HN titles: no uppercase for emphasis, no exclamation marks, don't editorialize.[4]
- To add a new list to the main awesome list, the list must be at least 30 days old; individual awesome lists set their own rules for adding projects.[5]
A 4-week launch timeline
Week 1 · four weeks out
- Write the README top section and record the GIF.
- Add license, CONTRIBUTING and a code of conduct.
- Label 5–10 good first issues.
Week 2 · three weeks out
- Set topics and the social preview image.
- Tag v0.1 with release notes (template).
- Publish a docs page on your own domain.
Week 3 · two weeks out
- Share with ten developers who have the problem; fix what confuses them.
- Draft the Show HN post (template).
- Find the awesome lists and newsletters for your ecosystem and read their rules.
Week 4 · launch week
- Write a short "why I built this" post for your blog.
- Set up issue templates.
- Pick a weekday morning (US time) when you can stay online.
Launch-day checklist
- Post Show HN with a plain title and a first comment explaining why you built it.
- Stay in the thread for hours; answer critiques with specifics.
- Post in the ecosystem's community following its rules.
- Triage issues and merge easy fixes the same day.
- Thank contributors publicly in the next release notes.
After launch: SEO steps
Launch boards reset; search pages don't. These steps keep people finding you after launch week.
- Write docs pages that answer the exact error messages and tasks people search.
- Publish comparison pages with alternatives, fairly, with a feature table.
- Link the repo, docs and package registry pages to each other.
- Keep releases and a changelog so the project looks maintained.
Common mistakes
- A README that starts with badges and installation before saying what the project does.
- No license, which stops adoption at companies.
- Asking for stars or upvotes in group chats.
- Launching and disappearing; unanswered issues in week one look like abandonment.
Templates for this launch
- Show HN postA Show HN template that follows Hacker News rules: a plain title, a link people can try, and a first comment on why you built it and how it works.
- Release notesRelease notes for a notable launch or version: what's new, why it matters, how to use it, upgrade steps and known issues, with a filled example.
- Changelog entryA changelog entry template grouped by Added, Changed, Fixed and Removed, written for users rather than commit logs, with a filled example.
- Reddit launch postA Reddit launch post template written as a story, not an ad, plus a checklist for subreddit self-promotion rules so your post isn't removed.
FAQ
Where should I launch an open-source project?
Show HN, the communities for your language or framework, and relevant awesome lists and newsletters. Make sure the README works before any of them.
What size is the GitHub social preview image?
GitHub recommends at least 640×320 and 1280×640 for best display, under 1 MB.
How do I get into an awesome list?
Each list has its own contributing rules, usually in contributing.md. Read them and open a pull request that follows the format.
Do GitHub stars matter?
They're a social signal and some package managers use them for acceptance (Homebrew's policy uses stars, forks or watchers). Earn them with a good README; don't ask for them.
Sources
- GitHub Docs: Customizing your repository's social media preview
- GitHub Docs: Classifying your repository with topics
- Hacker News: Show HN guidelines
- Hacker News guidelines
- sindresorhus/awesome: List submission requirements
Checked . Platforms change their rules; open the source before you rely on a number.
Related launch guides
- How to launch a CLI toolLaunch a command-line tool: install paths (Homebrew tap vs core, winget, npm, pip), terminal GIFs, Show HN and docs that rank for the problems it solves.
- How to launch an npm packageLaunch an npm package: package.json fields, provenance and trusted publishing, a README that sells, and where JavaScript developers look.
- How to launch a Python libraryLaunch a Python library on PyPI: pyproject metadata, README rendering, classifiers, trusted publishing, docs that rank, and where Python developers look.
- How to launch a developer APILaunch a developer API: time to first call, docs, OpenAPI, a Postman public workspace, keys and limits, and docs pages that rank.