TinyTorch/MODULE_MIGRATION_STRATEGY.md

Module Migration & Testing Strategy

Overview

Systematic migration of TinyTorch modules to nbgrader with comprehensive testing at each step.

Per-Module Testing Checklist

1. Instructor Solution Verification

• Verify complete instructor solution exists (*_dev_enhanced.py)
• Test instructor solution executes without errors
• Verify all nbgrader markers are present (### BEGIN/END SOLUTION)
• Test nbdev export works (tito module export <module>)
• Verify exported package functionality
• Run module tests (tito module test <module>)

2. Assignment Generation & Validation

• Generate assignment (tito nbgrader generate <module>)
• Verify assignment file structure in assignments/source/<module>/
• Inspect generated assignment for proper student scaffolding
• Verify nbgrader metadata is correct (point values, cell types)
• Test assignment loads properly in Jupyter

3. NBGrader Workflow Testing

• Release: tito nbgrader release <module>
• Collect: Simulate student submission and tito nbgrader collect <module>
• Autograde: tito nbgrader autograde <module>
• Feedback: tito nbgrader feedback <module>
• Verify each step creates appropriate directory structure

4. Student Journey Simulation

• Copy released assignment to student workspace
• Attempt to complete assignment as student
• Verify student scaffolding is helpful but not giving away answers
• Test submission process
• Verify auto-grading catches both correct and incorrect solutions

5. Integration Testing

• Test nbdev integration (tito module export <module>)
• Verify package functionality after export
• Test integration with other modules (dependencies)
• Verify CLI commands work correctly
• Test module status reporting

6. Documentation & Git

• Document any issues found and resolved
• Update module README if needed
• Commit changes with descriptive message
• Tag successful completion

Testing Framework Setup

Directory Structure for Testing

testing/
├── instructor/          # Instructor workspace
├── student/            # Student workspace simulation
├── submissions/        # Mock student submissions
└── logs/              # Test execution logs

Mock Student Workflow

1. Setup Student Environment: Clean workspace with released assignments
2. Attempt Solutions: Implement partial/complete/incorrect solutions
3. Submit: Place in appropriate submission directory
4. Grade: Run auto-grading pipeline
5. Feedback: Generate and review feedback

Integration Points

• NBDev Export: After each module, test package export
• Dependencies: Verify new modules work with previously migrated ones
• CLI Integration: Test all tito commands work correctly

Module Migration Order

1. 00_setup - Foundation, no dependencies
2. 01_tensor - Core data structure
3. 02_activations - Mathematical functions
4. 03_layers - Depends on activations
5. 04_networks - Depends on layers
6. 05_cnn - Advanced layers
7. 06_dataloader - Data processing

Success Criteria per Module

• ✅ Instructor solution executes perfectly
• ✅ NBGrader workflow completes without errors
• ✅ Student assignment is educational and challenging
• ✅ Auto-grading works correctly
• ✅ Package integration maintained
• ✅ All tests pass
• ✅ Documentation updated

Risk Mitigation

• Backup Strategy: Keep original files until migration confirmed
• Rollback Plan: Each module can be reverted independently
• Testing Isolation: Test each module in isolation before integration
• Progressive Integration: Add modules incrementally to package

Execution Timeline

• Per Module: ~30-45 minutes comprehensive testing
• Total Estimated: 3-4 hours for complete migration
• Checkpoints: After every 2 modules, full integration test

Documentation Requirements

• Issue Log: Track and resolve any problems found
• Solution Notes: Document any non-obvious implementation details
• Student Feedback: Note areas where student scaffolding could improve
• Integration Notes: Document inter-module dependencies and interactions