How to Contribute a New App to Awesome Free Apps: A Complete Guide

To contribute a new app to Awesome Free Apps, open a discussion issue first, edit the appropriate markdown list using the required format and icon conventions, prefix your commit message with "Add:", and submit a pull request targeting the main branch.

Awesome Free Apps is a curated list of free, cross-platform applications maintained in the Axorax/awesome-free-apps repository. Whether you are adding a desktop utility or a mobile tool, following the standardized workflow ensures your contribution passes automated CI checks and gets merged quickly.

Open an Issue Before Editing

Always start by creating an issue using the Blank issue template. This allows maintainers to discuss the addition and verify that the app meets the inclusion criteria before you spend time on the pull request.

👉 Create a new issue

This step prevents duplicate entries and confirms the app aligns with the project's quality standards.

Edit the Correct Markdown File

You must edit only two specific files when contributing a new app. Modifying other files—especially auto-generated content—will cause CI failures.

Choose Between README.md and MOBILE.md

• Desktop applications: Edit README.md
• Mobile applications: Edit MOBILE.md

Never modify files in the filter/ directory. These contain auto-generated tables of contents and category filters that are maintained by the renew-categories workflow.

Placement and Formatting Rules

Append your new entry at the bottom of the relevant category. Do not reorder existing items or insert entries alphabetically.

Use this exact markdown format:

- [AppName](https://example.com) – Short description of the app. 🪟 🟢

Icon reference:

• 🪟 – Windows support
• 🍎 – macOS support
• 🐧 – Linux support
• 🟢 – Open-source software
• ⭐ – Recommended/featured

Add icons immediately after the description with single spaces between them.

Concrete Example

Below is a valid entry for a fictional Windows-only open-source tool called WinPower, added to the System Customization section in README.md:

## System Customization

- [WinPower](https://github.com/Axorax/winpower) – Advanced power settings and management for Windows. 🪟 🟢

Place this line at the end of the category list, save the file, and stage your changes.

Follow Conventional Commit Prefixes

The repository uses automated changelog generation. Your commit message must use one of these exact prefixes:

• Add: AppName – When adding a new entry
• Update: AppName – When modifying an existing entry
• Remove: AppName – When deleting an entry

For the WinPower example above, the commit command would be:

git commit -m "Add: WinPower"

Submit Your Contribution

Push your changes to a forked repository and open a Pull Request targeting the main branch.

CI Validation

The maintainers will run automated checks, including the renew-categories workflow, to ensure your entry follows syntax rules and category placement. PRs that modify the filter/ directory or break markdown formatting will be rejected automatically.

Once the CI passes and a maintainer approves the addition, your PR will be merged and the app will appear in the list.

Summary

• Start with an issue: Use the Blank issue template to discuss the addition first
• Edit the right file: Modify only README.md (desktop) or MOBILE.md (mobile), never the filter/ directory
• Format correctly: - [Name](URL) – Description. [icons]
• Append only: Add entries at the bottom of categories; do not reorder existing items
• Commit convention: Use Add:, Update:, or Remove: prefixes
• Target main: Submit PRs to the main branch and wait for CI checks to pass

Frequently Asked Questions

What is the exact markdown format for adding an app?

The entry must follow this pattern: - [AppName](https://url.com) – Description text here. 🪟 🟢. Note the en-dash (–) after the link, not a hyphen. Include relevant platform icons (🪟 for Windows, 🍎 for macOS, 🐧 for Linux) and 🟢 if the app is open-source.

Should I edit the table of contents in the filter directory?

No. The filter/ directory contains auto-generated tables of contents and category filters. These files are maintained automatically by the renew-categories workflow and should never be edited manually. Only modify README.md or MOBILE.md.

How do I indicate platform support and open-source status?

Place icons immediately after the description: 🪟 for Windows, 🍎 for macOS, 🐧 for Linux, and 🟢 for open-source. You may also add ⭐ to indicate a recommended application. Separate multiple icons with single spaces.

What commit prefix should I use when updating an existing app?

Use Update: AppName when modifying an existing entry (such as updating the URL or description), and Remove: AppName when deleting an entry. The Add: prefix is reserved strictly for new additions to the list.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}