How to Promote an Open Source Project Without a Budget

Most open source promotion advice is written for one of two people: a team with a marketing budget, or a foundation with a dozen maintainers. You are probably neither. You have a repo, some evenings, and a project that solves a real problem for a small group of people who do not know it exists yet. Here is a plan sized for that.

What does a README need before you share anything?

The README is the page every link you ever post will land on, so it has to work for a stranger who has thirty seconds and zero context. Open Source Guides makes the starting point plain: before you promote anything, you should be able to explain what the project does and why it matters, framed around what users want rather than how clever the internals are. The GitHub Blog's maintainer interviews say the same thing from the other direction: the most common mistake is too much technical terminology, when what people care about is why they should use it.

Turn that into a checklist you can test:

README element	What to write	Done test
First line	What it does and who it is for, in one sentence with no jargon	A non-user can repeat it back
Proof it works	A screenshot, terminal recording or short demo GIF	Visible without scrolling
Install and first run	The shortest path to a visible result	Works on a clean machine
One real example	The task a user came for, end to end	Copy, paste, result
Honest comparison	One line on how it differs from the obvious alternative	Names the alternative
Where to go next	Docs, issues, contributing guide	Every link resolves

Test the install on a machine that has never seen your project. Every complaint you would get on launch day is a setup failure you could find first. If you need a shot list for the demo, the demo GIF guide covers what to film in twenty seconds.

Then do the small repository settings that help people find you. GitHub's docs say topics help other people find and contribute to a project, and that they should describe its purpose, subject area or language. Add a description and a website link in the About box. Upload a social preview image too, because until you do, a link to your repo shows only basic information and the owner's avatar when someone pastes it into a chat or a post. GitHub recommends at least 640 by 320 pixels and 1280 by 640 for the best display, in a file under 1MB.

Last item: pick one home URL. Open Source Guides suggests having a single place to point people, and for most projects that is the repository itself. A separate site is optional.

Where do open source projects get a fair hearing?

Different places suit different projects, and the same post can be welcome in one and removed from another. These are the rules as published by each community, checked on 28 October 2026. Rules change, so read the current version before you post.

Where	What the rules say	Best fit
Hacker News (Show HN)	Something people can run or try, non-trivial, with you around to discuss it. No landing pages. Do not ask friends to upvote	A working tool with a no-signup way to try it
r/opensource	Repo must carry an OSI-listed license file. Use the Promotional flair for shared projects. Excessive self-promotion and drive-by posting are rules	Any properly licensed project, from an active account
r/programming	"I made this" demo posts are not allowed; a technical write-up on what was hard or interesting can be	A genuine engineering story, not a feature list
r/selfhosted	Promoted apps must be production ready and have docs; projects under three months old go in the New Project Megathread	Things people run on their own hardware
Awesome lists	Each list has its own contribution rules, often strict	A mature project that fits a curated list
Language and ecosystem forums, newsletters, meetups	Vary by community; read the posting guidance	Projects with a clear ecosystem home

A few notes on reading that table.

Hacker News is for things people can try. The Show HN guidelines say Show HN is for something you have made that other people can play with, and that blog posts, sign-up pages and lists do not qualify. They also say the project should be non-trivial and that you should be around to discuss it. If you want the title and first-comment mechanics, the Show HN checklist walks through them line by line.

Reddit is several different rule sets. The subreddits above differ more than they look. r/opensource wants a license file and a Promotional flair. r/programming does not take project demo posts at all, but welcomes a technical write-up where the write-up is the point. r/selfhosted cares about documentation and keeps young projects in a megathread. Posting the same text in all three is how you get removed from all three.

Awesome lists are a slow channel, not a launch channel. The main Awesome list contribution template is a good example of how strict curation can be: its own checklist asks that a list has existed for at least 30 days and that submitters review other open pull requests first. Treat a placement as something you earn after the project has matured. For a wider map of non-open-source venues, see where to post your app.

The common thread from Open Source Guides is worth keeping: find people who already have the problem your project solves, answer their questions, and mention the project when it genuinely fits. A reply that solves someone's problem often outperforms a post that announces your repo.

How do you announce a release without repeating yourself?

This is the loop the whole plan hangs on. A solo project gets many small chances to be seen, one for each release, and each chance should be spent differently so your audience does not read the same post five times.

First, decide whether the release is worth announcing at all. Hacker News is explicit on one point: new features and upgrades, its example being "Foo 1.3.1 is out", are generally not substantive enough to be a Show HN, while a major overhaul is probably fine. Use that as your general filter. A patch release goes in the changelog and nowhere else. A release that adds something a user would tell a colleague about earns an announcement.

For the ones that do, run the same sequence in the same order:

1. Write release notes for people, not for the commit log. GitHub can generate release notes listing merged pull requests, contributors and a changelog link, which is a fine skeleton. Put a two or three sentence summary above it in your own words: what changed, who benefits, how to try it.
2. Update the README if the headline changed. If the release adds the thing people will come for, the first line and the demo should show it.
3. Post the announcement where your existing users are. Your own channel first: the repo's Discussions, your project's chat, your social account. These are people who already care.
4. Post once in one new place. Rotate which. Use the table above to pick the venue that fits this particular release, and keep the post specific to that release rather than re-introducing the whole project.
5. Write the thing that explains why. If the release involved a real problem, a short article on how you solved it gives you something a technical community will take, where a feature list will not.
6. Reply to everything for a few days. Replies are where users turn into contributors.

Here is the cadence as a table you can copy:

When	Action	Why
Before tagging	Run the install on a clean machine; check the README example	Catch setup failures before strangers do
Tag day	Publish the release with human notes on top	The release page is the permanent record
Same day	Tell your existing users	Warmest audience first
Within a week	One post in one new venue, tailored to the release	Fresh eyes, no repetition
Following days	Answer every reply and issue, fix what was reported	Responsiveness is the product
After that	Label two or three approachable issues	Give new people an entry point

How do you turn early users into contributors?

Contributors are not a separate audience you market to. They are users who ran into something small enough to fix. Your job is to make that path short.

The GitHub Blog's interviews with maintainers make the case for being responsive: do not let pull requests, issues and comments sit unanswered, because it signals the project is alive and that input is valued. You do not have to be on call all day. A reply within a couple of days that says "thanks, I'll look at this on Saturday" is enough.

Then add the small pieces of scaffolding:

• A CONTRIBUTING.md file. GitHub surfaces it to anyone opening an issue or pull request, and it tells people how to help. Say what you would welcome and what you would not.
• A handful of issues labeled good first issue. GitHub says the label helps people find them when searching and can increase the chance your issues are surfaced.
• Non-code work on the list. Documentation fixes, examples and bug reproductions are legitimate first contributions, and many users can do them without knowing your codebase.

When someone sends a first pull request, even a small one, thank them in public and merge fast if you can. That response teaches everyone watching what contributing to your project feels like.

What promotion backfires with developers?

Developers read a lot of launch posts and are quick to spot the pattern. These are the habits that cost you:

• Marketing language. Words that sound like an ad get ignored or removed. Say what the tool does, what it does not do, and what is rough.
• Asking for votes. Hacker News says plainly that asking friends to upvote or comment is not okay on the site. A post that needs help to climb was probably aimed at the wrong place.
• Posting once and leaving. r/opensource lists drive-by posting as a rule. If you are not around to answer, wait until you are.
• Copying one post across five venues. Every community's rules differ, and readers who follow several places notice the repeat.
• Announcing every patch. You use up attention you will want when the release that matters arrives.
• Overstating maturity. If the project is a weekend experiment, say so. People forgive rough edges and do not forgive being told it is production ready when it is not.

How do you tell if any of it is working?

Pick two or three signals and look at them after each release, not each day. Useful ones for a small project:

• Visitors who stay. The traffic graph under your repository's Insights shows views and clones. Compare the days after a release with the days before.
• Stars, as a rough signal only. They are cheap to give and tell you someone liked the page. They do not tell you someone used the project.
• Issues and discussions from people you do not know. This is the real signal. Someone installed it, tried it and cared enough to write.
• First-time contributors. One is more telling than a hundred stars.
• Where people say they found you. Ask in the issue template or in the first reply. It costs nothing and tells you which venue deserves the next post.

If a release produced traffic but no issues, the README is probably the weak point: people arrived and could not tell what to do. If it produced stars but nobody ran it, the install path is the weak point. Fix the page that is failing before you post anywhere new.

Where does TryMy fit?

If your project is something people can try, whether that is a hosted demo, a downloadable app or a tool with a clear install, it can sit alongside the places above. TryMy lists free-to-try indie apps, reviewed by a person before they go live. Dev tools have their own category, so developers browsing for tools see yours next to similar work. A listing will not replace the release loop. It is one more place a stranger can land and decide to click Try. The free listing is genuinely free.

If people can try it, TryMy will review it for a free listing. Submit it.

FAQ

Should I post my open source project on Hacker News?

If people can run it today and you can stay in the thread, yes. Hacker News says Show HN is for things others can try, and that landing pages and sign-up pages do not count. Make the tryout easy, ideally with no signup, write a plain title, and answer comments. Do not ask friends to vote. Small version bumps are generally not substantive enough, so save it for a real milestone.

Do open source projects belong on Product Hunt?

Product Hunt is a product launch site, so a project with an installable app or a hosted demo and a clear one-line pitch is the better fit there. A library with no visible product is usually easier to explain to developer communities. Check the current Product Hunt posting guidelines before you submit, since they change.

How do I get my project into an awesome list?

Find the list for your topic, read its contribution guidelines in full, and follow them exactly. Many lists have strict formatting, minimum project age and review requirements. The main Awesome list, for example, asks that a list be at least 30 days old and that submitters review other pull requests. Expect it to be a slow channel and submit only when your project is mature enough to deserve the placement.

Is it worth writing blog posts about an open source tool?

Yes, when the post is useful on its own. A write-up on a problem you solved, with the tool as the worked example, can be shared in places where a plain project link is not welcome, as r/programming's rules about technical write-ups show. A post that is only a feature list does little. Write one when a release gives you a real story, not on a schedule.