CONTRIBUTING.md

Contributing Guidelines

Thank you for your interest in contributing to this Python learning resource! This document provides guidelines for adding new content, improving existing materials, and maintaining consistency across the repository.

📋 Table of Contents

• How to Contribute
• Content Standards
• File Structure
• Templates
• Commit Guidelines

How to Contribute

Types of Contributions

1. New Topics - Add new learning topics to any level
2. New Problems - Create practice problems for existing topics
3. Improvements - Enhance explanations, examples, or exercises
4. Fixes - Correct errors, typos, or broken links
5. Documentation - Improve READMEs or add helpful notes

Before You Start

1. Check existing topics to avoid duplication
2. Review the templates in .templates/ directory
3. Ensure your Python code follows PEP 8 style guidelines
4. Test all code examples to ensure they work correctly

Content Standards

Learning Materials

Each topic should include:

1. README.md - Main learning content

   • 2-3 paragraph introduction explaining the topic and its importance
   • 5-8 specific learning objectives
   • Prerequisites with links to earlier topics
   • Table of contents linking to all files
   • Link to related problems
   • Navigation to next recommended topic

2. examples.py - Working code examples

   • 2-3 complete, runnable examples
   • Detailed comments explaining each line
   • Progressive complexity (basic → intermediate)
   • Include expected output in comments

3. exercises.md - Guided practice

   • 3-5 practice exercises
   • Difficulty progression (easy → medium → hard)
   • Clear instructions and expected outcomes
   • Hints for approach (not full solutions)

4. key-concepts.md - Quick reference

   • Bullet-point summary of main concepts
   • Syntax quick reference
   • Common patterns and idioms
   • Pitfalls to avoid

Problems

Each problem set should include:

1. problem-N.md - Problem statement

   • Clear, specific problem description
   • Input/output specifications
   • 2-3 example test cases with expected results
   • Constraints and requirements
   • Difficulty level and time estimate
   • Link to related learning material

2. problem-N-hint.md - Progressive hints

   • 3-4 progressive hints (from general approach to specific steps)
   • Each hint should guide without giving away the solution
   • Final hint can be more detailed

3. problem-N-solution.py - Complete solution

   • Working, well-commented code
   • Explanation of the approach
   • Alternative solutions if applicable
   • Test cases demonstrating correctness

4. problem-N-performance.md - Analysis

   • Time complexity analysis
   • Space complexity analysis
   • Optimization opportunities
   • Comparison of different approaches

File Structure

Topic Naming Convention

Use numbered prefixes for clear ordering:

01-topic-name/
02-another-topic/
03-yet-another-topic/

Level Organization

learning-guide/
├── beginner/
│   ├── README.md (level overview)
│   ├── 01-topic-name/
│   │   ├── README.md
│   │   ├── examples.py
│   │   ├── exercises.md
│   │   └── key-concepts.md
│   └── 02-next-topic/
├── intermediate/
└── advanced/

problems/
├── beginner/
│   ├── README.md (level overview)
│   ├── 01-topic-name/
│   │   ├── problem-1.md
│   │   ├── problem-1-hint.md
│   │   ├── problem-1-solution.py
│   │   ├── problem-1-performance.md
│   │   ├── problem-2.md
│   │   └── ... (2-3 problems per topic)
│   └── 02-next-topic/
├── intermediate/
└── advanced/

Templates

Use templates from .templates/ directory to ensure consistency:

• topic-README-template.md - For learning guide topics
• examples-template.py - For example code files
• exercises-template.md - For exercise files
• key-concepts-template.md - For quick reference guides
• problem-template.md - For problem statements
• hint-template.md - For hint files
• solution-template.py - For solution code
• performance-template.md - For performance analysis

Copy the appropriate template and fill in the content.

Code Quality

Python Code Standards

1. PEP 8 Compliance

   • Use 4 spaces for indentation
   • Maximum line length of 88 characters (Black formatter default)
   • Use descriptive variable names
   • Follow naming conventions (snake_case for functions/variables)

2. Comments

   • Explain why, not just what
   • Use docstrings for functions and classes
   • Keep comments up-to-date with code changes

3. Examples Must Work

   • All example code must execute without errors
   • Include print statements to show output
   • Test on Python 3.8+ before submitting

Markdown Standards

1. Links

   • Use relative links for internal navigation
   • Verify all links work before committing

2. Code Blocks

   • Always specify language: ```python
   • Include expected output when helpful

3. Formatting

   • Use headers hierarchically (don't skip levels)
   • Keep lines under 100 characters when possible
   • Use lists for scannable content

Testing Your Content

Before submitting, verify:

1. Code Runs

   # Test all Python files
   python3 your-file.py

2. No Syntax Errors

   python3 -m py_compile your-file.py

3. Links Work

   • Click through all internal links
   • Verify relative paths are correct

4. Consistent Style

   • Compare with existing topics
   • Use templates as guides

Commit Guidelines

Commit Message Format

<type>: <subject>

<body (optional)>

Types

• feat: - New topic or problem
• content: - Improvements to existing content
• fix: - Bug fixes or corrections
• docs: - Documentation updates
• style: - Formatting, no code change
• refactor: - Code restructuring

Examples

feat: Add beginner topic on list comprehensions

Add complete learning material and 3 practice problems
for list comprehensions topic.

---

fix: Correct example in control-flow topic

Fix syntax error in if-else example.

---

content: Expand error handling explanations

Add more context around try/except best practices
and common error types.

Review Process

1. Submit your changes
2. Ensure all tests pass
3. Respond to feedback
4. Make requested changes
5. Get approval and merge

Questions?

If you have questions about contributing:

• Open an issue for discussion
• Check existing topics as examples
• Refer to templates in .templates/

---

Thank you for helping make this a better learning resource! 🎓