# How to Create Properly Formatted Pull Requests for the Awesome Free Apps Project

> Learn to create properly formatted pull requests for the Awesome Free Apps project. Follow simple guidelines for editing README.md or MOBILE.md and using commit messages to contribute effectively.

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

---

**To create a properly formatted pull request for the Awesome Free Apps project, 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 at the bottom of the appropriate category using the exact Markdown syntax, and use terse commit messages with `Add:`, `Update:`, or `Remove:` prefixes.**

The Awesome Free Apps repository maintains a curated list of free software applications through a lightweight contribution workflow. Submitting a properly formatted pull request ensures that automated tooling—such as the table-of-contents generator and category filters—continues to function without requiring manual intervention from maintainers.

## Understanding the Editable File Structure

According to the source code in `Axorax/awesome-free-apps`, contributors must restrict edits to two specific files. The repository's automation depends on a strict separation between human-edited content and generated assets.

### Allowed Files for Editing

- **[`README.md`](https://github.com/Axorax/awesome-free-apps/blob/main/README.md)** – Contains the primary list of desktop applications
- **[`MOBILE.md`](https://github.com/Axorax/awesome-free-apps/blob/main/MOBILE.md)** – Contains mobile-only applications

### Files to Avoid

Never modify files within the `filter/` directory or any other auto-generated assets. These files are maintained by automation and will be overwritten, causing merge conflicts. The [`contributing.md`](https://github.com/Axorax/awesome-free-apps/blob/main/contributing.md) file explicitly warns that changes to generated files will be rejected.

## Formatting New Entries Correctly

Each application entry must follow a precise Markdown pattern to ensure the parsers can extract metadata correctly.

### Placement Within Categories

Locate the appropriate category section (e.g., `## Audio`, `## Browsers`) within [`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 your new entry **at the very bottom** of that category's list. Do not attempt to maintain alphabetical order or insert entries between existing lines—automation handles sorting.

### Required Markdown Syntax

Use this exact format, ending with a period:

```markdown
- [AppName](https://github.com/username/repo) - Brief description of functionality. 🪟 🟢.

```

The line must start with a dash and space, followed by the linked app name in brackets, then a space, hyphen, space, description, platform icons, and a closing period. For example:

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

```

## Commit Message and PR Title Conventions

The repository enforces a terse, keyword-based subject line that signals the automation about the change type. According to [`contributing.md`](https://github.com/Axorax/awesome-free-apps/blob/main/contributing.md), use one of three strict prefixes:

- **`Add:`** – For new app entries
- **`Update:`** – For modifying existing entries (typos, icon additions)
- **`Remove:`** – For deleting deprecated or incorrect entries

### Format Requirements

The commit message should contain **only** the prefix and the app name:

```text
Add: Winpower

```

The PR title must match this format exactly. For updates:

```text
Update: Winpower

```

Avoid additional text, punctuation, or descriptions in the subject line.

## Step-by-Step PR Creation Process

Follow this workflow to ensure your contribution meets the repository standards.

1. **Fork the repository** using GitHub's interface or use the in-browser editor if you have direct commit access.

2. **Edit the correct file** ([`README.md`](https://github.com/Axorax/awesome-free-apps/blob/main/README.md) for desktop apps, [`MOBILE.md`](https://github.com/Axorax/awesome-free-apps/blob/main/MOBILE.md) for mobile) following the placement and syntax rules above.

3. **Write the commit message** using the `Add:`, `Update:`, or `Remove:` prefix followed by the app name.

4. **Click "Propose file change"** then **"Create pull request"**.

5. **Fill the PR title** with the same prefix and app name used in your commit.

6. **Add a concise description** explaining why the change is needed. For example: "Adding Winpower, a Windows-only power-management utility." Keep descriptions brief; extend discussions in comments if necessary.

## Summary

Creating properly formatted pull requests for the Awesome Free Apps project requires adherence to specific structural rules:

- **Only edit** [`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/` directory
- **Append entries** at the bottom of categories without reordering existing items
- **Use exact Markdown syntax**: `- [Name](URL) - Description. icons.`
- **Prefix commit messages** with `Add:`, `Update:`, or `Remove:` followed by the app name only
- **Match PR titles** to commit message format for automation compatibility

## Frequently Asked Questions

### Can I modify files in the filter/ directory to fix categories?

No. Files within the `filter/` directory are auto-generated by automation scripts. Editing these will cause your PR to be rejected because the changes will be overwritten by the next automated run. Only modify [`README.md`](https://github.com/Axorax/awesome-free-apps/blob/main/README.md) and [`MOBILE.md`](https://github.com/Axorax/awesome-free-apps/blob/main/MOBILE.md).

### What if my app belongs in multiple categories?

Choose the most appropriate single category for your app. The Awesome Free Apps project lists each application only once to avoid duplication. If you believe the categorization is incorrect, open an issue to discuss moving an existing entry rather than creating duplicates.

### How do I update an existing entry to fix a broken link?

Use the `Update:` prefix in your commit message and PR title. Edit the existing line in [`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) without changing the entry's position in the list. For example: `Update: Winpower` to correct a URL or add missing platform icons.

### Why does my PR need a specific commit message format?

The terse commit message format (`Add:`, `Update:`, `Remove:`) enables maintainers to quickly identify change types and allows automated tooling to regenerate the table of contents and category filters. Descriptive sentences in commit subjects break this automation and require manual cleanup.