Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
295 lines (222 loc) · 6.31 KB

CONTRIBUTING.md

File metadata and controls

295 lines (222 loc) · 6.31 KB

Contributing to Python Programming Examples

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.

🎯 Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Help others learn and grow
  • No harassment or discrimination

🚀 How to Contribute

1. Fork the Repository

Click the "Fork" button in the top-right corner of the GitHub page.

# Clone your fork
git clone https://github.com/yourusername/python-examples.git
cd python-examples

2. Create a Feature Branch

Always create a new branch for your work:

git checkout -b feature/your-feature-name

Branch Naming Conventions

  • feature/add-list-examples - for new features
  • fix/correct-typo-in-docs - for bug fixes
  • docs/improve-readme - for documentation improvements
  • test/add-unit-tests - for test additions

3. Make Your Changes

Code Style Guidelines

  • Follow PEP 8 style guide
  • Use meaningful variable names
  • Add comments for complex logic
  • Keep functions small and focused
  • Use type hints where appropriate

Example of Good Code Style

def validate_age(age: int) -> bool:
    """
    Validate if age is within acceptable range.
    
    Args:
        age: The age to validate
        
    Returns:
        True if age is valid, False otherwise
    """
    return 0 <= age <= 150

Documentation

  • Add docstrings to all functions
  • Include example usage in comments
  • Update README if adding new examples
  • Keep explanations clear and beginner-friendly

4. Commit Your Changes

Write clear, descriptive commit messages:

git commit -m "Add: New example for list comprehension"

Commit Message Format

  • Start with a type: Add, Fix, Docs, Test, Refactor
  • Use present tense ("add" not "added")
  • Be specific about what changed
  • Keep it under 72 characters

5. Push to Your Fork

git push origin feature/your-feature-name

6. Create a Pull Request

  1. Go to the original repository on GitHub
  2. Click "New Pull Request"
  3. Select your branch
  4. Add a clear title and description
  5. Submit the pull request

Pull Request Description Template

## Description
Brief description of what this PR does.

## Type of Change
- [ ] New feature
- [ ] Bug fix
- [ ] Documentation update
- [ ] Code improvement

## Changes
- Change 1
- Change 2
- Change 3

## Testing
How to test these changes:
1. Run `python examples.py`
2. Verify output matches expected results

## Related Issues
Closes #(issue number)

📝 Types of Contributions

1. New Examples

We welcome new beginner-friendly Python examples!

Requirements:

  • Code should demonstrate a single concept clearly
  • Include comments explaining the logic
  • Provide example output
  • Suggest learning concepts
  • Update README with the new example

Example Template:

# ============================================================================
# Example 6: List Basics
# ============================================================================
# This example demonstrates creating and accessing lists in Python

# Create a list
numbers = [1, 2, 3, 4, 5]

# Access elements by index
print(numbers[0])      # Output: 1
print(numbers[-1])     # Output: 5

# Slice a list
print(numbers[1:3])    # Output: [2, 3]

# Loop through a list
for num in numbers:
    print(num)

2. Documentation Improvements

  • Fix typos and grammatical errors
  • Clarify explanations
  • Add more examples
  • Improve formatting
  • Update links and resources

3. Bug Fixes

  • Report bugs in issues first
  • Include steps to reproduce
  • Provide expected vs actual behavior
  • Submit a fix with explanation

4. Tests

  • Add unit tests in tests/ directory
  • Use Python's unittest or pytest
  • Aim for good code coverage
  • Test edge cases

5. Code Quality

  • Improve code readability
  • Optimize performance
  • Refactor repetitive code
  • Add type hints

📋 Checklist Before Submitting

  • Code follows PEP 8 style guide
  • All functions have docstrings
  • Comments explain complex logic
  • Code is tested and working
  • README is updated if needed
  • No unnecessary files added
  • Commit messages are clear
  • PR description explains changes

🧪 Testing

Run the Examples

python examples.py

Run Tests (if applicable)

python -m pytest tests/
# or
python -m unittest discover

💡 Contribution Ideas

High Priority

  • Add more beginner-friendly examples
  • Improve code comments
  • Add unit tests
  • Fix documentation typos

Medium Priority

  • Add advanced examples
  • Create example breakdown videos
  • Add interactive exercises
  • Improve error messages

Nice to Have

  • Add more learning resources
  • Create comparison charts
  • Build a progression guide
  • Add visual diagrams

❓ Questions or Issues?

Getting Help

  1. Check existing issues first
  2. Search the documentation
  3. Ask in discussions
  4. Open a new issue with details

Opening an Issue

Include:

  • Clear title
  • Detailed description
  • Steps to reproduce (if bug)
  • Expected vs actual behavior
  • Python version and OS
  • Relevant code snippets

📚 Resources for Contributors

Python Best Practices

Git & GitHub

Writing Good Documentation

🎉 Recognition

Contributors will be recognized in:

  • This CONTRIBUTING.md file
  • Project README
  • Release notes
  • GitHub contributors page

📞 Contact

Questions about contributing? Feel free to:

  • Open a discussion
  • Check existing issues
  • Reach out to maintainers

Thank you for contributing! 🌟

Your help makes this project better for everyone learning Python.