🚀 repo-promotion-guide

The ultimate reference guide to platforms, communities, and strategies for promoting your open-source or side project on GitHub.

---

📌 Table of Contents

• Reddit
• Hacker News
• Product Hunt
• Dev Communities & Blogs
• Social Media
• GitHub-Specific Methods
• Aggregators & Directories
• Messaging & Chat Communities
• Newsletters & Email
• How to Polish Your Repository
• Tips for Writing Posts
• Launch Checklist

---

🟠 Reddit

Reddit is one of the best platforms to promote your project. The key is picking the right subreddits and never spamming.

General Tech Subreddits

Subreddit	Members	Notes
r/programming	~6M	High quality bar — must be genuinely interesting
r/webdev	~1.5M	Web development, frontend/backend
r/learnprogramming	~4M	Great if your project is educational
r/compsci	~700K	CS theory, algorithms, systems
r/coding	~300K	General coding discussions
r/tech	~15M	Broad tech audience

Showcase & Side Projects

Subreddit	Description
r/coolgithubprojects	Made specifically for sharing GitHub repos
r/SideProject	Pet projects, indie apps, side hustles
r/opensource	Any kind of open-source project
r/github	All things GitHub
r/selfhosted	Self-hosted tools and services
r/devops	DevOps, CI/CD, infra tooling
r/hacking	Security tools (if relevant)
r/netsec	Network security, must be high quality
r/MachineLearning	ML/AI research and projects
r/artificial	AI projects for a broader audience
r/datascience	Data science tools and libraries
r/gamedev	Game engines, frameworks, tools

Language-Specific Subreddits

Subreddit	Language
r/Python	Python
r/rust	Rust
r/javascript	JavaScript
r/golang	Go
r/java	Java
r/cpp	C++
r/typescript	TypeScript
r/swift	Swift
r/kotlin	Kotlin
r/dotnet	.NET / C#
r/ruby	Ruby
r/php	PHP
r/haskell	Haskell
r/elixir	Elixir
r/scala	Scala
r/zig	Zig

Framework & Tool Subreddits

Subreddit	Topic
r/reactjs	React
r/vuejs	Vue.js
r/svelte	Svelte
r/nextjs	Next.js
r/node	Node.js
r/docker	Docker
r/kubernetes	Kubernetes
r/androiddev	Android development
r/iOSProgramming	iOS development
r/emacs	Emacs plugins
r/neovim	Neovim plugins
r/vscode	VS Code extensions
r/commandline	CLI tools
r/linux	Linux tools & distros
r/homelab	Homelab / self-hosted infrastructure

Reddit Best Practices

• Read the rules of each subreddit before posting — many ban direct self-promotion.
• Use the [Project] or Show r/...: prefix in the title where accepted.
• Reply to every comment — it boosts the post's ranking and shows you care.
• Best time to post: Tuesday–Thursday, 9–11 AM EST.
• Don't cross-post the same text to multiple subreddits simultaneously — it gets flagged.
• Karma matters: have some history on the platform before posting.
• Engage with the community first — upvote others, leave comments.

---

🟡 Hacker News

Hacker News is one of the most influential platforms in tech. Hitting the front page is a massive boost.

Post Formats

• Show HN: [Name] – [One-line description] — the standard format for showing projects.
  • Example: Show HN: I built a CLI tool that auto-generates commit messages using GPT
• Ask HN — use when you genuinely want feedback or opinions.

HN Best Practices

• The title must be honest and descriptive — no hype or clickbait.
• In your first comment, tell the story: why you built it, what problem it solves, what's interesting technically.
• Never ask for upvotes — it violates the rules and can get your post flagged.
• Best time: Monday–Friday, 7–9 AM Eastern (US audience wakes up).
• Aim for quality over frequency — one great Show HN beats ten mediocre ones.
• Engage with every comment, especially critical ones.
• If it doesn't land the first time, you can repost after a few weeks with improvements.

---

🟣 Product Hunt

Product Hunt is the go-to platform for indie makers and developers launching products.

How to Launch

1. Create your account weeks before launch — build some karma by commenting on others' projects.
2. Prepare your assets: logo (240×240px), screenshots, optional demo video, and a punchy tagline.
3. Launch on Tuesday or Wednesday — highest traffic days.
4. Build a supporter list in advance — you need upvotes in the first few hours.
5. Write a detailed maker comment explaining the problem, solution, and your journey.
6. Link your GitHub repo prominently in the description.

Product Hunt Tips

• Actively answer all comments and questions on launch day.
• Share your launch link in communities, newsletters, and social media on launch day.
• Don't game it with fake accounts — PH detects it.
• A coming soon page helps you gather followers before the launch.
• Good products with great stories beat polished products with no story.

---

✍️ Dev Communities & Blogs

Dev.to

dev.to — a massive, friendly community of developers.

• Write articles in the "I built X, here's how" format.
• Use tags: #opensource, #showdev, #programming, #webdev, #buildinpublic.
• A series of posts (e.g., "Building X in public — Part 1, 2, 3...") outperforms a single post.
• Cross-post from your own blog using the canonical URL feature.

Hashnode

hashnode.com — developer blogging on your own domain.

• Create a blog on your custom domain powered by Hashnode.
• Publish technical deep-dives about building your project.
• Cross-post with dev.to.

Medium / Towards Data Science / The Startup

• Great for ML, data science, or business-oriented projects.
• Submit to large publications to reach their existing audience.
• "Towards Data Science" has millions of readers for ML/AI content.

Lobsters

lobste.rs — a curated, invite-only community with a very technical audience.

• Requires an invitation to join, but high signal-to-noise ratio.
• Great for systems programming, security, and niche topics.

Indie Hackers

indiehackers.com — platform for indie developers and entrepreneurs.

• Add your project to the "Products" section.
• Join and post in topical groups.
• Share revenue/growth milestones — the community loves transparency.

DZone

dzone.com — technical articles aggregated by topic zones.

• Submit articles about technical aspects of your project.
• Good for enterprise/Java/DevOps audience.

---

📱 Social Media

Twitter / X

Twitter/X remains the primary social network for developers.

• Use hashtags: #buildinpublic, #opensource, #100daysofcode, #indiedev, #sideproject, #showdev.
• Thread format works best: problem → solution → demo → link.
• Tag accounts related to the technologies you use (e.g., @reactjs, @rustlang) — they often retweet cool projects.
• Post GIFs or short screen recordings — they get dramatically more engagement than plain text.
• Build in public (#buildinpublic) before your release to grow an audience beforehand.
• Reply to popular devs in your niche — visibility through conversation.
• Post updates consistently, not just at launch.

LinkedIn

• Best for projects related to productivity, business, enterprise, or career development.
• Personal posts outperform company page posts — always post from your personal account.
• LinkedIn articles get strong organic reach.
• Use hashtags: #opensource, #programming, #developer, #softwareengineering.

YouTube

• Record a short demo video (2–5 minutes) showing what your project does.
• Format "I built X in N days" performs very well as both a long video and a Short.
• YouTube Shorts and TikTok for quick demos (<60 seconds).
• Tutorials that use your project as an example attract ongoing traffic.

TikTok

• Short code/project demos get surprisingly large organic reach.
• "Day in the life of a developer" content with your project featured.

Mastodon

• Active tech community at fosstodon.org and hachyderm.io.
• Use hashtags: #foss, #opensource, #programming.

---

⭐ GitHub-Specific Methods

GitHub Topics

• Add relevant topics in Settings → About → Topics.
• Use popular ones: awesome, hacktoberfest, machine-learning, cli, rest-api, productivity, developer-tools, etc.
• Topics make your repo discoverable through GitHub's Explore and search.

Awesome Lists

• Find awesome-[your-topic] lists on GitHub and submit a Pull Request.
• Examples: awesome-python, awesome-rust, awesome-selfhosted.
• Being listed here is a permanent, passive source of traffic and stars.
• Make sure your PR follows the list's contribution guidelines exactly.

GitHub Trending

• Getting on Trending is a massive boost. It requires many stars in a short window.
• A coordinated launch (all promotions on the same day) maximizes your chances.
• Check github.com/trending to understand the volume needed.

Hacktoberfest

• Add the hacktoberfest topic to your repo every October.
• Create beginner-friendly issues labeled hacktoberfest or good first issue.
• This attracts contributors, PRs, and organic attention.

GitHub Sponsors & Discussions

• Enable GitHub Sponsors to make it easy for users to support you.
• Use GitHub Discussions as a community forum — it signals an active project.
• Respond to issues quickly — responsiveness is visible and builds reputation.

Stars Notifications

• Thank users who open issues or contribute — they often star and share.
• Add a "Give a ⭐ if this helped you" line in your README.

---

📚 Aggregators & Directories

Resource	Description
LibHunt	Library catalog — you can submit your project
AlternativeTo	Add your tool as an alternative to known software
SourceForge	Old but still has significant traffic
Slant	Q&A format — add as an option to relevant questions
Openbase	Open-source package catalog with reviews
GitHunt	GitHub Trending browser extension
OSSInsight	GitHub analytics, useful for showcasing growth
Repography	Generates visual activity cards for your README
TLDR pages	If your project is a CLI tool, submit a tldr page
Terminal Trove	Directory of CLI/TUI tools
Toolbox for Startups	Tool catalog for developers and founders
Futurepedia	AI tools directory (for AI projects)
There's An AI For That	AI tools aggregator
Free for Dev	If your tool has a free tier, get listed here

---

💬 Messaging & Chat Communities

Discord

Discord has thousands of developer servers, most with a #show-and-tell or #projects channel.

Server	Focus
Reactiflux	React ecosystem
Python Discord	Python
Rust Community	Rust
The Programmer's Hangout	General programming
Nodeiflux	Node.js
Vue Land	Vue.js
Svelte	Svelte
TypeScript Community	TypeScript
DevCord	General dev community
Machine Learning	ML/AI

• Always read the server rules before posting.
• Engage with the community first — don't just drop a link and leave.
• Write a short, interesting description when sharing, not just a bare URL.

Slack

Many professional Slack workspaces have project showcase channels.

• Frontend Developers Slack
• DevOps Slack
• iOS Developers Slack
• DataTalks.Club (data/ML)
• Elixir Slack, Ruby on Rails Link, etc.

Telegram

Thousands of developer groups exist on Telegram. Search for your tech stack.

• Many language/framework specific channels with tens of thousands of members.
• Search @username style channels in your niche.

---

📧 Newsletters & Email

Most newsletters have a submission form — use it. Editors are always looking for interesting projects.

Language & Tech Newsletters

Newsletter	Focus	Submit
TLDR	General tech	tldr.tech/submit
JavaScript Weekly	JavaScript	Has submission link in footer
Python Weekly	Python	Has submission link
Golang Weekly	Go	Has submission link
This Week in Rust	Rust	Open PR on GitHub
Node Weekly	Node.js	Has submission link
Bytes	JavaScript	Has submission link
React Status	React	Has submission link
DB Weekly	Databases	Has submission link
DevOps Weekly	DevOps	Has submission link
StatusCode Weekly	General dev	Has submission link
Hacker Newsletter	HN top links	Depends on HN performance
Console	Developer tools	Via their website

Cold Outreach

• Find bloggers, YouTubers, and newsletter authors in your niche.
• Write a short, personal email — explain the project and why their audience would care.
• Offer to write a guest post or be interviewed.
• Don't mass-email — personalize each message.

---

🎨 How to Polish Your Repository

A great repo promotes itself. Before announcing anything, make sure these are in order.

README.md

• One-liner description at the very top — what does it do and for whom.
• Screenshot or GIF near the top — people decide in seconds whether to read further.
• Clear sections: Features, Installation, Usage, Configuration, Contributing, License.
• Badges: build status, version, license, code coverage, downloads.
• A "Why this project?" or "Motivation" section builds connection.
• Demo link or hosted example if possible.

Repository Settings

• Fill in the About section with description, website, and topics.
• Set correct Topics (see above).
• Keep Releases updated with changelogs.
• Add a CONTRIBUTING.md — lowers the barrier for contributors.
• Add Issue and Pull Request templates.
• Pin the most important issue or discussion.

License

• MIT or Apache 2.0 are the most popular and permissive choices.
• Without a license, people legally cannot use your code.
• Add a LICENSE file to the root of the repo.

Code Quality Signals

• CI badge (GitHub Actions, CircleCI).
• Test coverage badge.
• No broken links in README.
• Clear and consistent commit history.

---

📝 Tips for Writing Posts

What Works

• Tell a story: why you built it, what problem you had, how you solved it.
• Show results: screenshots, GIFs, demo links — always lead with visuals.
• Be honest: mention challenges, failures, and lessons learned — it builds trust.
• End with a question to invite comments and discussion.
• Mention your tech stack — developers are always curious about the tools used.
• Keep it concise — developer audiences skim.

Title Formulas That Work

• I built X to solve Y problem
• Show HN: [Name] – [what it does in 5 words]
• After N months, I finally released [Project]
• Why I rewrote X in Rust/Go/etc
• [Project]: open-source alternative to [known tool]
• I got tired of paying for X, so I built my own
• [Project] — a [language] library for doing Y

What to Avoid

• Clickbait and exaggeration — developer audiences see through it immediately.
• Spamming links in comment sections of unrelated posts.
• Cross-posting the same text without adapting it to each community.
• Launching without a working demo, screenshots, or README.
• Being defensive about criticism — constructive feedback is gold.
• Posting and ghosting — always stay engaged in the discussion.

---

📊 Metrics & Analytics

Track where your traffic comes from:

• GitHub Insights — built-in traffic, clones, and referrer data.
• UTM parameters on your links to know which platforms convert best.
  • Example: github.com/you/repo?utm_source=reddit&utm_medium=post&utm_campaign=launch
• star-history.com — visualize your star growth over time.
• ossinsight.io — deep GitHub analytics and comparisons.

---

🔄 Launch Checklist

[ ] README.md ready: description, screenshots/GIF, install + usage instructions
[ ] License added (MIT recommended)
[ ] Topics set in GitHub About
[ ] Demo link or hosted example ready
[ ] Dev.to / Hashnode article written
[ ] Reddit posts prepared (adapted per subreddit)
[ ] Show HN post drafted
[ ] Product Hunt launch planned (assets ready)
[ ] Tweet / thread written with screenshot
[ ] Newsletter submissions sent
[ ] Awesome list PR submitted
[ ] Discord/Slack communities identified
[ ] UTM links ready for tracking

---

⚡ Quick Start: Top 5 Actions for a New Project

1. Post on r/coolgithubprojects and r/SideProject with the format: [Project] Name — what it does
2. Submit Show HN on Hacker News (morning EST for best timing)
3. Write an article on dev.to with the tag #showdev
4. Post a tweet with #buildinpublic and a screenshot or GIF
5. Find the relevant awesome-[topic] list and submit a Pull Request

---

🌟 Bonus: Long-Term Growth Strategies

• Write tutorials that use your project — brings in search traffic for years.
• Answer Stack Overflow questions in your domain and mention your tool when genuinely relevant.
• Speak at meetups or conferences — even local ones matter.
• Integrate with popular tools — being listed in official docs of a major framework is huge.
• Maintain the project actively — users share and recommend maintained projects.
• Build a community around the project (Discord server, mailing list).
• Respond to every issue — reputation spreads by word of mouth.

---

Found a platform that's missing? Open an issue or submit a PR — contributions welcome!