How to Launch an Open-Source Project (2026)

README, License and Docs First

An open-source launch sends people to your repository, and most decide on the README whether to stay. Before you post anywhere, get three things right.

The README

GitHub's own README docs suggest covering what the project does, why it's useful, how to get started, where to get help and who maintains it. GitHub shows a README from the repository's root, its docs folder or its hidden .github folder. For a launch, the first screen matters most:

1. one plain sentence on what it does and who it's for;
2. a screenshot, GIF or short code example showing it working;
3. one install command;
4. a minimal example that runs exactly as written;
5. links to the full docs and the license.

Test the quick start on a clean machine or in a fresh container. A launch-day issue titled "install doesn't work" costs you more readers than any missing feature.

The license

Code on GitHub isn't open source until it has a license. GitHub's licensing docs say that without one, default copyright laws apply: you keep all rights, and others can't copy, distribute or build on your code without your permission. Add a LICENSE file to the root. If you're not sure which to pick, choosealicense.com, which GitHub created, explains the common ones. Decide before launch, because changing a license after other people have contributed can get complicated.

The docs

Docs don't need to be a website on day one. A docs folder with installation, configuration, a few worked examples and a troubleshooting page is enough, plus a changelog so early users can see what changed between versions.

Give People Something to Try

Most people who click your launch link won't clone the repository. Give them a way to see it work in under a minute:

• Libraries: a runnable example in an online playground, or a short code snippet with its real output underneath.
• Command-line tools: a GIF or terminal recording of a real run at the top of the README, plus a one-line install.
• Self-hosted apps: a hosted demo with sample data that resets regularly, or a single docker run command that starts it.
• Visual tools: a live demo page and three or four screenshots of real use.

This isn't only good manners. Hacker News' Show HN guidelines ask you to make it easy for users to try your project, ideally without signups or emails. If your demo needs an account, explain why, or offer a read-only version. Our guide to making a product demo video covers recording a short walkthrough, and the launch asset resizer crops screenshots to the sizes boards ask for.

GitHub Settings That Help Discovery

A few repository settings decide how your project looks in search, in link previews and on GitHub itself. They take half an hour.

Description and website

The About box on your repository's main page holds a one-line description and a website link. Use the same plain sentence as your README, and point the website at your docs or demo. It's often the first text a stranger reads about the project, so write it for them.

Topics

Topics put your repository on GitHub's topic pages, such as github.com/topics/cli, where people browse projects by subject. GitHub's topics docs allow up to 20 per repository, each using lowercase letters, numbers and hyphens, and 50 characters or less. Cover the language, the framework, the category and the problem: a Rust command-line tool for compressing images might use rust, cli, image-compression and webp. Pick topics people actually browse, not every word that loosely applies.

Social preview

When someone shares your repository on X, Slack or a forum, the social preview image is what shows. Without one, the preview shows basic repository information and the owner's avatar. GitHub's social preview docs ask for a PNG, JPG or GIF under 1 MB, at least 640 by 320 pixels, and 1280 by 640 for the best display. Put the project name, the one-line description and a glimpse of the product on it. GitHub supports transparent PNGs, but a solid background is the safe choice, since some platforms don't show transparency well. The OG image previewer shows how a shared link will look.

Releases

Tag a version before launch, even v0.1.0, so people have something stable to install and pin. GitHub releases are based on Git tags, can generate release notes for you, and let people get notified of new releases without following every other change in the repository. For command-line tools, attach built binaries so people can try it without a toolchain. Some curated lists also require a numbered release, as you'll see below.

Community files

GitHub's community profile checks whether a public repository has recommended files such as a README, a code of conduct, a license and contributing guidelines, plus issue templates. Fill them in before launch. The contributing file matters most, and the last section covers it.

Posting a Show HN

Show HN is often the best single place for an open-source launch: posting is free, placement isn't for sale, and the readers will actually run your code. Read our Show HN review for how its pages and links work, then check the rules on the day you post. Hacker News' Show HN guidelines say:

• it must be something people can run on their computers or hold in their hands;
• blog posts, sign-up pages, newsletters, lists and landing pages don't qualify;
• it must be something you worked on personally and are around to discuss;
• you shouldn't ask friends to upvote or comment.

Keep the title plain: what it is and what it does. Link the repository if the README is your best introduction, or the demo if the project is visual. Then add a first comment straight away, in your own voice:

Plan to spend several hours answering questions, and expect blunt ones about your design choices. Answer them calmly and specifically. Our guide to writing a Show HN post covers the title, the comments and what to do if your post sinks.

Subreddits and Awesome Lists

Subreddits

The Reddit communities that suit open source are mostly about a language or a use case: communities for Rust, Go, Python or JavaScript, r/opensource, r/selfhosted for apps people run on their own servers, and r/SideProject for feedback from other builders. Each one sets its own rules. Some welcome project posts any day, some keep them to a weekly thread, some don't allow them at all, and some require a flair or title format. Read the sidebar or About tab on the day you post, not from memory.

Pick two or three that fit, post a few days apart, say you're the author, and explain your technical choices: language communities care about how something is built as much as what it does. Our guide to launching on Reddit covers posting without getting removed, and the Reddit post generator gives you a first draft to rewrite.

Awesome lists

Awesome lists are curated lists of projects on GitHub, usually one per language or topic, and sindresorhus/awesome is an index of them. Developers use them to find tools, and a listing stays up long after launch week.

Each list sets its own bar, usually in a contributing file. Awesome Go's guidelines, for example, ask for at least 5 months of history since the first commit, an open-source license and at least one version-numbered release. So for many projects, awesome lists come a few months after launch, not on launch day. When you're ready, open one pull request per list, add a single line in the list's own format and the right category, and describe the project plainly. Don't send the same pull request to dozens of lists at once: maintainers are volunteers, and they notice.

Launch Boards and What They Send

Launch boards reach people who browse new products rather than search for them. For developer-facing projects, DevHunt is a weekly launchpad for developer tools, with a free listing and paid launches. General boards like Product Hunt and Peerlist work too, especially for apps with a visual interface. On Hauntboard, a person reviews every launch (free ones in about 72 hours), and each launch page shows its page views, visits sent and votes in public. Our list of places to launch covers more, and the launch directory tracker keeps your submissions in one place.

Stars are easy to count and easy to over-read: they measure interest, not use. To see what each channel actually sent:

• GitHub traffic: anyone with push access can open the Insights tab, then Traffic, to see visitors from the past 14 days, clones, referring sites and popular content, as GitHub's traffic docs describe. Check it during launch week and note the numbers, because the window moves on.
• Your docs or demo site: tag the links you control with UTM parameters using the UTM builder.
• Downloads and issues: package downloads, if you publish to a registry, and issues from people you don't know are better signs of real use than stars.

Our guide to tracking launch traffic explains the setup in more detail.

Turning First Users Into Contributors

Most users of an open-source project never contribute, and that's normal. The few who do usually start small: a typo fix, a bug report with a clear reproduction, a missing example. Your job is to make that first step obvious and the first experience a good one.

1. Write a contributing guide. Put CONTRIBUTING.md in the root, docs or .github folder. GitHub's contributor guidelines docs say people see a link to it when they open an issue or a pull request. Include how to set the project up locally, how to run the tests, and what makes a pull request easy to accept.
2. Label a few good first issues before launch. GitHub's docs on labels say the good first issue label can make your issues more likely to be surfaced to new contributors. Five to ten is plenty. In each one, say which file to look at and what "done" looks like.
3. Reply within a day during launch week, even if it's only "Thanks, I'll look at this on Saturday." A first pull request that sits unanswered for weeks is often the last one from that person.
4. Turn good bug reports into invitations. When someone reports a bug with a clear reproduction, ask whether they'd like to try the fix, and offer to point them to the right place in the code.
5. Credit people in public. Release notes that GitHub generates list the release's contributors. Thank first-time contributors by name too, in the release and wherever you post the update.
6. Say what you won't accept. A short roadmap and a note on what's out of scope save contributors from building features you'd have to turn down.

Then keep shipping small releases. Each one is a reason to post an update, a chance to thank contributors, and proof to new visitors that the project is alive. When your README, license and first release are ready, submit your project to Hauntboard alongside your Show HN.