How to Contribute a New Project Idea to the App Ideas Collection: A Complete Guide

To contribute a new project idea to the App Ideas Collection, fork the florinpop17/app-ideas repository, create a markdown file following the template in Example Guide.md, place it in the appropriate tier folder under Projects/, and submit a pull request against the master branch.

The App Ideas Collection by florinpop17/app-ideas is a curated repository of project ideas designed to help developers improve their skills through practical application building. Contributing your own app idea follows a standardized markdown-based workflow that ensures consistency across the entire collection.

Understanding the Repository Structure

The repository organizes projects into three distinct difficulty tiers. Each tier corresponds to a numbered subdirectory under the Projects/ folder:

• Projects/1-Beginner/ – Entry-level projects focusing on fundamental concepts
• Projects/2-Intermediate/ – Projects requiring integration of multiple technologies
• Projects/3-Advanced/ – Complex applications involving architecture decisions and advanced patterns

According to the repository's README.md, the tier system helps developers filter projects by their current skill level. When you contribute a new project idea, you must select the tier that accurately reflects the complexity of the proposed application.

Preparing Your Contribution

Before writing any content, review the official documentation to ensure your submission meets community standards.

Read the Contribution Guidelines

Start by reading CONTRIBUTING.md in the root directory. This file outlines the complete workflow, including branch naming conventions and commit message standards. The repository also provides an Example Guide.md file that serves as the mandatory template for all new project ideas.

Verify Uniqueness

Search the existing Projects/ directory to confirm your idea does not duplicate an existing entry. You can use GitHub's search functionality or locally search with grep to scan for similar project titles or descriptions. Each project idea must be unique to maintain the collection's value.

Creating Your Project Idea File

New contributions are single markdown files placed in the appropriate tier folder. The file must follow a strict naming convention and content structure.

File Naming and Location

Name your file using the format Project-Name-App.md (e.g., Weather-Widget-App.md). Place the file in the subdirectory matching your selected tier:

• Beginner ideas go in Projects/1-Beginner/
• Intermediate ideas go in Projects/2-Intermediate/
• Advanced ideas go in Projects/3-Advanced/

Template Structure

Copy the content from Example Guide.md and populate the following required sections:

• Application Name – The title of your project
• Tier – Must be 1-Beginner, 2-Intermediate, or 3-Advanced
• Description – A concise overview of the application's purpose and features
• User Stories – Checklist of functionality users should be able to perform
• Bonus features – Additional challenges for extended learning
• Useful links and resources – Documentation, tutorials, or APIs relevant to the project
• Example projects – Links to existing implementations for reference

Below is a complete example of a properly formatted intermediate project file. Save this as Projects/2-Intermediate/My-Cool-Game-App.md:

# My Cool Game

**Tier:** 2-Intermediate

A simple browser‑based puzzle game where users match colored tiles within a time limit.

## User Stories

- [ ] User can start a new game session.
- [ ] User can select difficulty level (easy, medium, hard).
- [ ] User can see a countdown timer.
- [ ] User can earn points for each correct match.
- [ ] User can view a high‑score leaderboard.

## Bonus features

- [ ] User can pause and resume the game.
- [ ] Add sound effects for matches and timer.
- [ ] Store high scores in local storage.

## Useful links and resources

- https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API
- https://www.w3schools.com/jsref/prop_html_innerhtml.asp

## Example projects

- https://github.com/example/tile-matcher
- https://github.com/example/puzzle-game

Submitting Your Contribution

Once your markdown file is complete and properly formatted, submit it through GitHub's standard pull request workflow.

Commit and Push

Create a dedicated branch for your contribution (e.g., add-my-cool-game-idea). Commit the new markdown file with a descriptive message such as "Add My Cool Game app idea to Intermediate tier". Push the branch to your forked repository.

Open a Pull Request

Navigate to the upstream florinpop17/app-ideas repository and create a pull request against the master branch. In your PR description, briefly summarize the application concept and specify which tier folder contains your new file.

Address Review Feedback

Maintainers may request minor edits regarding formatting, typos, or content clarity. Apply any requested changes to the same branch and push the updates; the pull request will automatically reflect these modifications.

Summary

• Repository structure: Projects are organized into three tiers (1-Beginner, 2-Intermediate, 3-Advanced) under the Projects/ directory
• Template requirement: All submissions must use the structure defined in Example Guide.md
• File naming: Use Project-Name-App.md format and place files in the correct tier subdirectory
• Validation: Search existing files to ensure your idea is unique before submitting
• Submission: Fork the repository, commit to a feature branch, and open a PR against master

Frequently Asked Questions

What file format is required for new app ideas?

All contributions must be written in Markdown (.md files). The repository explicitly uses markdown to ensure consistent rendering on GitHub and easy readability. You must base your file on the Example Guide.md template to maintain uniformity with existing projects in the Projects/ folder.

How do I determine which tier my project belongs to?

Consult the README.md file for tier definitions. Beginner projects involve single-page applications with minimal API integration. Intermediate projects require state management, routing, or external API usage. Advanced projects involve complex architectures, authentication systems, or real-time data handling. Select the tier that matches the primary learning objectives of your idea.

Can I submit multiple project ideas in a single pull request?

No, the contribution guidelines recommend submitting one idea per pull request. This allows maintainers to review each concept individually and ensures faster merging. If you have multiple ideas, create separate branches and pull requests for each distinct project file.

What happens after my pull request is merged?

Once merged into the master branch, your project idea automatically appears in the tier-specific list within the main README.md. The file becomes part of the permanent collection, accessible to developers worldwide who use the repository to find practice projects. You retain credit as the contributor through GitHub's commit history.

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