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

> Learn how to contribute a new app to Awesome Free Apps. Follow our guide to open a discussion, edit markdown, and submit a pull request to the Axorax/awesome-free-apps repository.

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

---

**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](https://github.com/Axorax/awesome-free-apps/issues/new?template=Blank+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`](https://github.com/Axorax/awesome-free-apps/blob/main/README.md)
- **Mobile applications**: Edit [`MOBILE.md`](https://github.com/Axorax/awesome-free-apps/blob/main/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:

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

```markdown

## 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:

```bash
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`](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 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`](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).

### 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.