Submission Criteria and Guidelines for Adding Apps to Awesome Free Apps: A Complete Contributor's Guide

To add an app to Awesome Free Apps, you must edit only README.md or MOBILE.md, append entries to the bottom of categories, follow strict one-sentence description formatting rules, and use commit messages formatted as Add: AppName.

The Axorax/awesome-free-apps repository maintains a curated list of free software through a strict, opinionated contribution process. All submissions must meet specific formatting, quality, and workflow criteria defined in contributing.md and full-guide.md. Pull requests that deviate from these guidelines are rejected until corrected.

Which Files You Can Edit

Contributions are limited to two specific markdown files. According to contributing.md, you may only modify:

• README.md – Contains desktop applications
• MOBILE.md – Contains mobile applications

Never edit the filter/ folder. This directory contains auto-generated categories and filters that the repository's GitHub Actions workflow regenerates automatically after your pull request merges. Touching these files will cause your PR to be rejected immediately.

Entry Format and Placement Rules

New entries must follow a precise markdown structure and placement convention.

Location Requirements

As documented in full-guide.md#adding-an-app-to-an-existing-category, append all new entries to the bottom of the appropriate category or sub-category. Do not insert apps alphabetically or by perceived importance.

Syntax Template

Use this exact format:

- [AppName](https://app-website-or-repo) - Concise description of features. 🪟 🟢

• The app name links to the official website or repository
• A hyphen and space (- ) separate the link from the description
• Emojis appear only after the description, not before

Description Style Requirements

The full-guide.md#description-rules section mandates strict formatting for app descriptions:

• One sentence only, ending with a period (.)
• No leading articles – omit "A", "An", or "The" at the start
• No extra punctuation – do not use exclamation points (!) or question marks (?)
• Feature-focused – highlight the most useful functionality for users

Correct example:

- [Winpower](https://github.com/Axorax/winpower) - Advanced power-settings manager for Windows. 🪟 [🟢](https://github.com/Axorax/winpower)

Incorrect example:

- [Winpower](https://github.com/Axorax/winpower) - A tool that manages power settings! 🪟 🟢

Platform Icons and Open Source Links

Repository guidelines in full-guide.md#recommended-icon-requirements specify how to indicate platform support and licensing.

Platform Support

Use the emoji table at the top of README.md to select appropriate platform indicators:

• 🪟 for Windows
• 🍎 for macOS
• 🐧 for Linux
• 🍎 for iOS
• 🤖 for Android

Open Source Attribution

If the app is open-source, the green square emoji (🟢) must be a clickable link to the source repository:

[🟢](https://github.com/username/repo)

For proprietary software, omit the green square or use only the platform emoji.

Commit Message Conventions

The repository enforces specific commit message prefixes defined in contributing.md:

• Add: AppName – When introducing a new application
• Update: AppName – When modifying an existing entry
• Remove: AppName – When deleting an app from the list

Example:

git commit -m "Add: Winpower"

Non-standard commit messages delay review and merge processes.

Pull Request Workflow

The complete submission process from full-guide.md#suggesting-an-app-or-any-support involves four steps:

1. Open an issue or discuss the addition on Discord before beginning work
2. Fork the repository, edit the appropriate markdown file (README.md or MOBILE.md), and push to a feature branch
3. Submit a PR using the correct commit message format
4. Wait for automation – A maintainer runs the Update main file GitHub Action after merging to regenerate the table of contents and filter files

Do not attempt to manually update the table of contents or the filter/ directory contents.

App Quality Standards

Beyond formatting, submissions must meet functional criteria specified in full-guide.md:

• Functional GUI – Command-line only tools are excluded
• Reasonable performance – Apps must run efficiently for their category
• Trustworthy developer – Prefer open-source projects from established maintainers
• Popularity – Apps should be reasonably well-known or widely used in their niche

Summary

• Edit only README.md (desktop) or MOBILE.md (mobile); never touch the filter/ folder
• Append entries to the bottom of categories using the exact format: - [Name](URL) - Description. emoji
• Write one-sentence descriptions without articles or extra punctuation
• Link the 🟢 emoji to the source repository for open-source apps
• Use commit prefixes Add:, Update:, or Remove: followed by the app name
• Open an issue before submitting, then let maintainers handle the automated TOC regeneration

Frequently Asked Questions

Can I edit the files in the filter folder to organize my submission?

No. The filter/ directory contains auto-generated content that the repository's CI pipeline creates. According to contributing.md, modifying these files results in immediate PR rejection. The Update main file GitHub Action handles all filter and TOC regeneration after your merge.

What commit message should I use when fixing an existing app entry?

Use the prefix Update: followed by the app name. For example: git commit -m "Update: Winpower". The repository requires this format for all modifications, while Add: is reserved for new entries and Remove: for deletions.

How do I indicate that an app supports multiple platforms?

Place the appropriate platform emojis after the description period, using the emoji key in README.md. For example: 🪟 🍎 🐧 indicates Windows, macOS, and Linux support. Each emoji must appear after the description text, separated by spaces.

What happens after my pull request is merged?

A maintainer manually triggers the Update main file GitHub Action workflow. This automation regenerates the table of contents and updates the filter/ folder files to include your new entry. You do not need to perform these steps yourself.

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