Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
358 lines (254 loc) · 9.41 KB

CONTRIBUTING.md

File metadata and controls

358 lines (254 loc) · 9.41 KB

🤝 Contributing to Python Mini Projects

Thank you for your interest in contributing! We're excited to have you here. This project thrives on community contributions, and we welcome developers of all skill levels.

🌟 Ways to Contribute

There are many ways you can contribute to this project:

  • 🎮 Add new mini-projects - Create fun, educational Python projects
  • 🌐 Enhance the web app - Add new features or improve existing ones
  • 🐛 Fix bugs - Help improve existing projects (Python or web)
  • 📚 Improve documentation - Make instructions clearer
  • 🎨 Enhance UI/UX - Add better emojis, animations, or visual elements
  • 💡 Suggest features - Share your ideas for improvements
  • ✅ Review pull requests - Help maintain code quality

🚀 Getting Started

1. Fork & Clone

# Fork the repository on GitHub (click the Fork button)

# Clone your fork
git clone https://github.com/YOUR_USERNAME/python-mini-project.git

# Navigate to the project
cd python-mini-project

# Add upstream remote
git remote add upstream https://github.com/ORIGINAL_OWNER/python-mini-project.git

2. Create a Branch

# Create a new branch for your feature
git checkout -b feature/your-project-name

# Or for bug fixes
git checkout -b fix/bug-description

3. Make Your Changes

  • Write your code following our Project Guidelines
  • Test your project thoroughly
  • Ensure it follows the repository style

4. Commit Your Changes

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "Add: Magic 8 Ball game with emoji UI"

5. Push & Create Pull Request

# Push to your fork
git push origin feature/your-project-name

# Go to GitHub and create a Pull Request

📋 Project Guidelines

When creating or modifying projects, please follow these guidelines:

✅ Python Projects - Code Style

  • No Functions/Classes - Keep code simple and procedural for beginners
  • Use Emojis - Make the UI visually appealing with relevant emojis
  • Clear Comments - Add comments for complex logic
  • Proper Spacing - Follow PEP 8: blank lines between sections
  • Consistent Formatting - Match the style of existing projects

✅ Python Projects - Structure

Your project should include:

# 1. Welcome message with emojis
print("🎮 Project Name 🎮")
print("Brief description\n")

# 2. Main game/tool logic with clear sections

# 3. User input with emoji prompts
choice = input("🎯 Your prompt: ")

# 4. Appropriate feedback messages
print("✅ Success message")
print("❌ Error message")

# 5. Goodbye/thank you message
print("\n👋 Thanks for playing!\n")

✅ Web App Projects - Structure

For web implementation, add to web-app/js/projects.js:

// 1. HTML Template Function
function getYourProjectHTML() {
    return `
        <div class="project-content">
            <h2>🎮 Your Project Name</h2>
            <!-- Your HTML structure -->
        </div>
        
        <style>
            /* Your project-specific styles */
        </style>
    `;
}

// 2. Initialization Function
function initYourProject() {
    // Get DOM elements
    const btn = document.getElementById('yourBtn');
    
    // Add event listeners
    btn.addEventListener('click', () => {
        // Your logic here
    });
}

// 3. Register in getProjectHTML() and initializeProject()

✅ Web App Projects - Guidelines

  • Vanilla JavaScript - No frameworks (React, Vue, etc.)
  • Responsive Design - Works on mobile, tablet, and desktop
  • CSS Variables - Use existing theme variables
  • Animations - Add smooth transitions and effects
  • Accessibility - Use semantic HTML and proper labels

✅ Requirements

  • Python 3.10+ - Use modern Python features
  • No External Dependencies - Only use standard library
  • Zero Setup - Project should run immediately
  • Cross-Platform - Works on Windows, Mac, and Linux

✅ Naming Convention

  • Put each Python project under a category folder (games/, math/, or utilities/) and keep it in its own folder: category/Project-Name/Project-Name.py
  • Use hyphenated names: My-Project-Name.py
  • Be descriptive: Rock-Paper-Scissor.py not game.py
  • Use title case for multi-word names: Number-Guessing-Game.py
  • Match existing naming pattern in repository

🎨 Emoji Guidelines

Use emojis to make your projects engaging! Here are some recommendations:

Purpose Emojis
Welcome/Title 🎮 🎯 🎲 🎰 🔢 🔺 📻 🪙 🐢 🌟 🌈
Success ✅ 🎉 🎊 ✨ 🏆 💯
Error ❌ ⚠️ 🚫
Input Prompt ➡️ 🎯 🤔 📝
Output/Result 📊 💡 🔍 📍
Information 💬 📚 ℹ️ 💡
Graphics/Art 🐢 🎨 🌟 🌈 💎 🌸 💫 ⭐ 🌺
Goodbye 👋 🙏 💖

🎯 Adding a New Mini-Project

Checklist

Before submitting your project, ensure:

Python CLI Version

  • Project runs without errors
  • Uses emojis for visual appeal
  • Has clear welcome message
  • Includes user prompts with emojis
  • Provides appropriate feedback
  • Has goodbye message
  • Code is properly formatted (PEP 8)
  • No external dependencies
  • Follows naming convention
  • Works on different operating systems
  • Is beginner-friendly and educational

Web App Version

  • Added to web-app/js/projects.js
  • Registered in getProjectHTML() mapping
  • Registered in initializeProject() mapping
  • Uses responsive design
  • Has smooth animations
  • Follows existing design patterns
  • Works on mobile devices
  • Updated project card in index.html (if new)

Documentation

  • Updated README.md with project description
  • Added to appropriate category (Games, Math, etc.)
  • Included usage instructions
  • Added to project count badge

Example Python Project Template

print("🎮 Project Name 🎮")
print("Description of what this project does\n")


# Main logic here
while True:
    choice = input("🎯 Make your choice (option1/option2): ").lower()
    
    if choice == "option1":
        # Handle option 1
        print("✅ Success message\n")
    
    elif choice == "option2":
        # Handle option 2
        print("❌ Error or different message\n")
    
    else:
        print("⚠️ Invalid input\n")
        continue
    
    # Ask to continue
    again = input("Continue? (y/n): ").lower()
    if again != 'y':
        break


print("\n👋 Thanks for using Project Name! Goodbye!\n")

🐛 Reporting Bugs

Found a bug? Help us improve!

  1. Check existing issues - Make sure it hasn't been reported
  2. Create a new issue with:
    • Clear title describing the bug
    • Steps to reproduce
    • Expected vs actual behavior
    • Python version and OS
    • Screenshots if applicable

💡 Suggesting Features

Have an idea? We'd love to hear it!

  1. Check existing issues - See if someone suggested it already
  2. Create a new issue with:
    • Clear feature description
    • Why it would be useful
    • Possible implementation approach
    • Examples if applicable

📝 Pull Request Guidelines

Before Submitting

  • ✅ Test your code thoroughly (both Python and web versions)
  • ✅ Follow the project guidelines
  • ✅ Update README.md if adding a new project
  • ✅ Add project card to index.html if new
  • ✅ Ensure no external dependencies (Python)
  • ✅ Check for spelling/grammar errors
  • ✅ Test web version in multiple browsers
  • ✅ Verify responsive design on mobile

PR Description Should Include

  • What: Brief description of changes
  • Why: Reason for the changes
  • How: How you implemented it
  • Testing: How you tested it (Python + Web if applicable)
  • Screenshots: If UI changes (especially for web app)

Example PR Title

  • ✅ Good: Add: Hangman game with emoji UI and web version
  • ✅ Good: Fix: Dice roller emoji display bug in web app
  • ✅ Good: Enhance: Add dark mode toggle to web interface
  • ❌ Bad: Update
  • ❌ Bad: Fixed stuff

⚡ Quick Tips

  • 🎯 Keep it simple - Remember, this is for beginners
  • 🎨 Make it fun - Use emojis and engaging messages
  • 📚 Be educational - Code should teach Python concepts
  • 🧪 Test thoroughly - Run your project multiple times
  • 💬 Be descriptive - Clear variable names and comments
  • 🤝 Be respectful - Follow the code of conduct

🎓 Learning Resources

New to contributing? Check these out:

🤔 Questions?

  • 💬 Open an issue for questions
  • 📧 Contact the maintainers
  • 💡 Check existing issues and PRs

🎉 Recognition

All contributors will be:

  • 🌟 Listed in the project contributors
  • 💖 Appreciated in release notes
  • 🏆 Recognized for their valuable contributions

Thank you for contributing to Python Mini Projects! 🎉

Your contributions help thousands of learners worldwide!

⬆ Back to Top