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

To create a properly formatted pull request for the Awesome Free Apps project, edit only README.md or 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 – Contains the primary list of desktop applications
• 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 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 or 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:

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

- [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, 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:

Add: Winpower

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

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 for desktop apps, 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 (desktop) or 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 and 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 or 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.

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