Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
235 lines (180 loc) · 7.09 KB

CONTRIBUTING.md

File metadata and controls

235 lines (180 loc) · 7.09 KB
Raw

Contributing to TinyTorch 🔥

Thank you for your interest in contributing to TinyTorch! This educational ML framework is designed to teach systems engineering principles through hands-on implementation.

🎯 Contributing Philosophy

TinyTorch is an educational framework where every contribution should:

  • Enhance learning - Make concepts clearer for students
  • Maintain pedagogical flow - Preserve the learning progression
  • Follow systems thinking - Emphasize memory, performance, and scaling
  • Keep it simple - Educational clarity over production complexity

🚀 Getting Started

Development Setup

  1. Clone and setup environment:

    git clone https://github.com/harvard-edge/cs249r_book.git
cd TinyTorch
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .

  2. Verify installation:

    tito system health
tito module status

  3. Read the development guidelines:

    • CLAUDE.md - Complete development standards
    • docs/INSTRUCTOR_GUIDE.md - Educational context
    • docs/development/ - Technical guidelines

🛠️ Types of Contributions

1. Module Improvements

  • Fix bugs in educational implementations
  • Improve documentation and explanations
  • Add better examples or visualizations
  • Enhance systems analysis sections

2. Testing & Validation

  • Add test cases for edge conditions
  • Improve checkpoint validation
  • Enhance integration tests
  • Fix failing test cases

3. Documentation

  • Improve module explanations
  • Add better ML systems insights
  • Create additional examples
  • Fix typos and clarity issues

4. Examples & Demos

  • Create new working examples
  • Improve existing example performance
  • Add visualization and analysis
  • Fix broken demonstrations

📋 Development Process

MANDATORY: Follow Git Workflow Standards

# 1. Always use virtual environment
source .venv/bin/activate

# 2. Create feature branch (NEVER work on dev/main directly)
git checkout dev
git pull origin dev
git checkout -b feature/your-improvement

# 3. Make changes following standards in CLAUDE.md
# 4. Test thoroughly
python tests/run_all_modules.py
tito module test 01

# 5. Commit with descriptive messages (NO auto-attribution)
git add .
git commit -m "Fix tensor broadcasting bug in Module 02

- Resolve shape mismatch in batch operations
- Add comprehensive test cases
- Update documentation with edge cases"

# 6. Merge to dev when complete
git checkout dev
git merge feature/your-improvement
git branch -d feature/your-improvement

Critical Policies - NO EXCEPTIONS

  • ✅ Always use virtual environment (.venv)
  • ✅ Always work on feature branches
  • ✅ Always test before committing
  • 🚨 NEVER add Co-Authored-By or automated attribution
  • 🚨 NEVER add "Generated with Claude Code"
  • 🚨 Only project owner adds attribution when needed

🧪 Testing Requirements

All contributions must pass:

  1. Module Tests:

    python tests/module_XX/run_all_tests.py

  2. Integration Tests:

    python tests/integration/run_integration_tests.py

  3. Module Testing:

    tito module test XX

  4. Example Verification:

    cd examples/xornet && python train.py
cd examples/cifar10 && python train_cifar10_mlp.py

📝 Code Standards

Module Development

For Students (using the framework):

  • File Format: Edit *_dev.ipynb notebooks in Jupyter Lab
  • Location: Notebooks are in modules/NN_name/ directories
  • Testing: Run tests inline as you build
  • Export: Use tito module complete N to export to package

For Contributors (improving the framework):

  • Source Files: Edit *_dev.py files (source of truth)
  • Notebooks: Generated from source files using tito src export
  • Structure: Follow the standardized module structure
  • Testing: Include immediate testing after each implementation
  • Systems Analysis: MANDATORY memory and performance analysis
  • Documentation: Clear explanations for educational value

Code Quality

  • Clean Code: Readable, well-commented implementations
  • Educational Focus: Prioritize clarity over optimization
  • Error Handling: Helpful error messages for students
  • Type Hints: Where they enhance understanding

🎓 Educational Guidelines

What Makes a Good Contribution

✅ Good Examples:

  • Fixes a bug that confuses students
  • Adds memory profiling to show systems concepts
  • Improves explanation of complex ML concepts
  • Creates working example that achieves good performance

❌ Avoid These:

  • Overly complex optimizations that obscure learning
  • Breaking changes that disrupt module progression
  • Adding dependencies that complicate setup
  • Removing educational scaffolding

Systems Focus

Every contribution should emphasize:

  • Memory usage and optimization
  • Computational complexity analysis
  • Performance characteristics
  • Scaling behavior and bottlenecks
  • Production implications

🐛 Bug Reports

When reporting bugs, include:

  1. Environment: OS, Python version, virtual environment status
  2. Module: Which module/checkpoint is affected
  3. Steps to Reproduce: Exact commands and inputs
  4. Expected vs Actual: What should happen vs what happens
  5. Error Messages: Full stack traces if applicable
  6. Testing: Did you run the module tests?
# Always include this information
python --version
echo $VIRTUAL_ENV
tito system health

🌟 Feature Requests

For new features, please:

  1. Check existing issues - Avoid duplicates
  2. Explain educational value - How does this help students learn?
  3. Consider module progression - Where does this fit?
  4. Propose implementation - High-level approach
  5. Systems implications - Memory, performance, scaling considerations

💬 Communication

  • Issues: Use GitHub Issues for bugs and feature requests
  • Discussions: GitHub Discussions for questions and ideas
  • Documentation: Check docs/ directory for detailed guides
  • Development: Follow CLAUDE.md for complete standards

🏆 Recognition

Contributors who follow these guidelines and make valuable educational improvements will be acknowledged in:

  • Module documentation where appropriate
  • Release notes for significant contributions
  • Course materials when contributions enhance learning

📚 Resources

Essential Reading

  • CLAUDE.md - Complete development standards and workflow
  • docs/INSTRUCTOR_GUIDE.md - Educational context and teaching approach
  • docs/development/ - Technical implementation guidelines

Quick References

  • Module Structure: See any modules/XX_name/ directory
  • Testing Patterns: Check tests/module_template/
  • Example Code: Look at examples/xornet/ and examples/cifar10/

Remember: TinyTorch is about teaching students to understand ML systems by building them. Every contribution should enhance that educational mission! 🎓🔥

Questions? Check the docs or open a GitHub Discussion.