How to get your GitHub project discovered

Your README is your landing page. The first screen should answer three questions:

• What is it? One plain sentence (“A CLI that turns Postman collections into typed API clients”), not a tagline.
• What does it look like? A screenshot, GIF or short terminal recording.
• How do I try it? Install and a first command in under a minute.

Then add a short feature list, a licence, and how to contribute. Put long docs further down, or elsewhere.

• Description and website. Fill in the repo’s About box with the same one-line description and a link to a demo or docs.
• Topics. Add the topics people browse: the language, framework, and what it does (for example cli, react, self-hosted).
• Social preview. Upload a social preview image, so links to your repo look good on X, Slack and Discord.
• A clear name. If the name is a pun, make sure the description carries the keywords people search for.

A repo nobody links to doesn’t get found. Pick two or three places your users actually hang out and write a real post for each: what you built, why, and what you learned. The full list is in where to promote your open-source project.

Avoid asking for stars. It reads as spam, and trading them breaks GitHub’s rules (see GitHub star-for-star).

• Ship visible releases with short changelogs. Each one is a reason to post again.
• Answer issues quickly. Early users who get a reply become your advocates.
• Label a few “good first issues” so contributors have an easy way in.
• Show it in use: a demo, an example project, or a blog post that solves a real problem with it.

On Stardeck, developers swipe through projects like yours and like the ones they’d use. Owners see anonymous feedback (views, like rate, and why people skipped), which is useful for sharpening your README and pitch. The leaderboard ranks people by real likes, never by GitHub stars.