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

> Learn the submission criteria and guidelines for adding apps to Awesome Free Apps. Follow formatting rules and commit message standards to contribute.

- Repository: [Axorax/awesome-free-apps](https://github.com/Axorax/awesome-free-apps)
- Tags: how-to-guide
- Published: 2026-05-26

---

**To add an app to Awesome Free Apps, you must edit only [`README.md`](https://github.com/Axorax/awesome-free-apps/blob/main/README.md) or [`MOBILE.md`](https://github.com/Axorax/awesome-free-apps/blob/main/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](https://github.com/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`](https://github.com/Axorax/awesome-free-apps/blob/main/contributing.md) and [`full-guide.md`](https://github.com/Axorax/awesome-free-apps/blob/main/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`](https://github.com/Axorax/awesome-free-apps/blob/main/contributing.md), you may only modify:

- **[`README.md`](https://github.com/Axorax/awesome-free-apps/blob/main/README.md)** – Contains desktop applications
- **[`MOBILE.md`](https://github.com/Axorax/awesome-free-apps/blob/main/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:

```markdown
- [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:**

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

```

**Incorrect example:**

```markdown
- [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`](https://github.com/Axorax/awesome-free-apps/blob/main/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:

```markdown
[🟢](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`](https://github.com/Axorax/awesome-free-apps/blob/main/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:**

```bash
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`](https://github.com/Axorax/awesome-free-apps/blob/main/README.md) or [`MOBILE.md`](https://github.com/Axorax/awesome-free-apps/blob/main/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`](https://github.com/Axorax/awesome-free-apps/blob/main/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`](https://github.com/Axorax/awesome-free-apps/blob/main/README.md) (desktop) or [`MOBILE.md`](https://github.com/Axorax/awesome-free-apps/blob/main/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`](https://github.com/Axorax/awesome-free-apps/blob/main/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`](https://github.com/Axorax/awesome-free-apps/blob/main/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.