How to submit a product to a GitHub awesome list

1. Prove the product fits before writing

An awesome list is curated, not an open advertising board. Read its title, scope, categories, current entries, README introduction, and any “not accepted” language. A product that is adjacent to the topic is not necessarily eligible.

• Find the narrowest section that accurately describes the product.
• Compare several existing entries in that section: product type, license, price model, maturity, and writing style.
• Check whether commercial tools, self-promotion, new products, or closed-source software are allowed.
• Skip the list when the rules or examples conflict with your product. Do not argue relevance into existence.

2. Read every repository instruction

Start with README.md, then look for CONTRIBUTING.md, a pull-request template, issue templates, and instructions linked from the README. Rules can cover alphabetical order, description length, punctuation, tests, branch naming, or a minimum period of product maturity.

The central Awesome contribution guide explains the basic browser-edit flow, but each list owns its own policy. The target repository's current files win.

3. Match the local entry format

Use nearby entries as a structural template, not as marketing inspiration. Preserve indentation, bullets, link style, punctuation, and ordering. Write a plain description of what the product does and who it helps. Avoid superlatives, keyword stuffing, emoji, pricing claims, and unverified numbers unless the repository explicitly uses them.

4. Make the smallest useful change

Add one entry in one correct place. Avoid reformatting surrounding lines, sorting the whole file, changing headings, or fixing unrelated text in the same proposal. Small diffs reduce review work and make intent obvious.

1. Fork or edit the repository using the method its instructions request.
2. Change only the relevant file and section.
3. Preview the Markdown and run any documented checks.
4. Review the final diff for accidental whitespace or unrelated edits.

GitHub's official documentation covers creating a pull request when the repository accepts that route.

5. Explain the proposal, not the promotion

Use the requested pull-request template. Otherwise, name the section, state what you added, and explain why it meets the visible criteria. Disclose a connection to the product when relevant. Do not promise traffic, demand a quick review, or contact maintainers on unrelated channels.

6. Treat review as a decision, not a queue

A maintainer may ask for edits, leave the proposal open, or decline it. Respond to specific feedback, update the existing branch when requested, and avoid duplicate pull requests. Silence is not acceptance, and merge speed is not guaranteed.

• If asked to reword or move the entry, make the narrow change and reply once.
• If the product is ineligible, close the proposal politely.
• If the repository appears inactive, record that fact and move on rather than escalating contact.

Pre-submission checklist

• Product clearly fits the list's topic and chosen section.
• Commercial, closed-source, or self-submitted products are allowed when applicable.
• README, contribution guide, and pull-request template were checked.
• Entry matches local syntax, order, tone, and length.
• Description is factual and connection to product is disclosed where useful.
• Diff contains no unrelated changes.
• No acceptance, traffic, backlink, or ranking outcome is assumed.