Documentation updates across the codebase:
Root documentation:
- README.md: Updated references from book/ to site/
- CONTRIBUTING.md: Updated build and workflow instructions
- .shared-ai-rules.md: Updated AI assistant rules for new structure
GitHub configuration:
- Issue templates updated for new module locations
- Workflow references updated from book/ to site/
docs/ updates:
- STUDENT_QUICKSTART.md: New paths and structure
- module-rules.md: Updated module development guidelines
- NBGrader documentation: Updated for module restructuring
- Archive documentation: Updated references
Module documentation:
- modules/17_memoization/README.md: Updated after reordering
All documentation now correctly references:
- site/ instead of book/
- modules/XX_name/ instead of modules/source/
Added clear documentation of the Source → Export → Use workflow:
Three Sacred Principles:
1. ONLY edit files in modules/source/ (source of truth)
2. ALWAYS use tito export to build tinytorch/ package
3. NEVER modify tinytorch/ directly (generated code!)
Key additions:
- Visual diagram showing modules/source/ → tito export → tinytorch/ → milestones/
- Explicit warning that tinytorch/ is generated (like node_modules/)
- Complete workflow example from edit to test to use
- Clear explanation of what each directory is for
- Warning that manual tinytorch/ edits will be lost
This ensures contributors understand that:
- modules/source/ = where you work
- tinytorch/ = generated package (don't touch!)
- milestones/ = use the exported package
- Emphasize always working in dev branch
- Main branch for stable releases only
- Recommend feature branches for all changes
- Add YAML-style description for Cursor
- Clear workflow steps and quick reference
- Replaced 3 overlapping documentation files with 1 authoritative source
- Set modules/source/08_optimizers/optimizers_dev.py as reference implementation
- Created comprehensive module-rules.md with complete patterns and examples
- Added living-example approach: use actual working code as template
- Removed redundant files: module-structure-design.md, module-quick-reference.md, testing-design.md
- Updated cursor rules to point to consolidated documentation
- All module development now follows single source of truth
- Enhanced tensor module documentation with mathematical foundations
- Improved explanations for scalars, vectors, and matrices
- Added NBGrader workflow documentation to activations module
- Cleaned up .cursor/rules/ directory structure
- Updated user preferences for better development workflow
These changes improve the educational content and developer experience
while maintaining the core functionality of all modules.
- Replace all 'python bin/tito.py' references with correct 'tito' commands
- Update command structure to use proper subcommands (tito system info, tito module test, etc.)
- Add virtual environment activation to all workflows
- Update Makefile to use correct tito commands with .venv activation
- Update activation script to use correct tito path and command examples
- Add Tiny🔥Torch branding to activation script header
- Update documentation to reflect correct CLI usage patterns
🔄 CONSOLIDATION: Merged separate testing patterns into module development best practices
�� COMPREHENSIVE GUIDE NOW INCLUDES:
- Complete testing architecture (inline → module → integration → system)
- pytest requirements for all testing levels (ALWAYS use pytest)
- Real data requirements for integration/system tests
- Stubbed dependencies for module-level isolation
- Detailed examples for each testing tier
- Anti-patterns covering testing mistakes
- Quality standards including testing requirements
- Complete development workflow with testing integration
🧪 TESTING ARCHITECTURE CLARIFIED:
- Inline unit tests: Immediate feedback in development code
- Module tests: pytest with stubbed dependencies (isolation)
- Integration tests: pytest with real modules and real data
- System tests: pytest with complete workflows and real datasets
📚 EDUCATIONAL BENEFITS:
- Students learn proper testing architecture
- Immediate feedback through inline tests
- Professional pytest usage throughout
- Real-world testing patterns and practices
- Clear separation of concerns across testing levels
This creates one comprehensive reference document for both module development and testing practices, eliminating duplication and ensuring consistency.
🔧 CRITICAL CORRECTION - Testing Architecture:
**Inline Unit Tests** (Immediate after each feature):
- Location: Inline in notebook/Python development code
- Purpose: Immediate feedback after implementing each component
- Data: Simple, hardcoded test data
- Example: assert result.shape == expected_shape right after implementation
**Module-Level Tests** (Isolated with stubs):
- Location: modules/source/XX_module/tests/test_module.py
- Purpose: Test module logic in isolation using fake/stubbed dependencies
- Data: FakeTensor, FakeLayer classes to avoid real module dependencies
- Example: Test Sequential with FakeLayer objects, not real Dense/ReLU
**Integration Tests** (Real cross-module):
- Location: tests/integration/ directory
- Purpose: Test how modules actually work together
- Data: Real implementations from tinytorch.core.*
- Example: Real Tensor → Real Dense → Real ReLU → Real Sequential
**System Tests** (Full end-to-end):
- Location: tests/system/ directory
- Purpose: Complete ML pipelines with real datasets
- Data: Real datasets and complete workflows
This correction ensures proper testing isolation and eliminates the confusion between unit tests (inline) and module-level tests (stubbed dependencies). Students learn proper testing architecture while maintaining development velocity.
Based on analysis of our best performing modules (Networks, Layers, DataLoader, CNN):
🧪 TESTING ARCHITECTURE:
- Emphasize test-after-each-feature development cycle
- Clear separation: module unit tests vs integration tests
- Module tests: modules/source/XX_module/tests/ (unit tests only)
- Integration tests: tests/ main directory (cross-module testing)
- Immediate unit tests after each component implementation
📚 EDUCATIONAL PATTERNS:
- Build → Use → Analyze/Test cycle with specific third-stage verbs
- Build → Use → Reflect (early modules: Setup, Tensor)
- Build → Use → Analyze (middle modules: Activations, Layers, Networks)
- Build → Use → Optimize (advanced modules: CNN, DataLoader, Autograd)
🏗️ MODULE STRUCTURE:
- Based on our gold standard modules (Networks, Layers, DataLoader)
- Clear examples of immediate testing patterns from CNN module
- Comprehensive testing strategies from all best modules
- Real-world examples and anti-patterns
⚡ DEVELOPMENT WORKFLOW:
- Complete module development cycle with quality gates
- Daily development rhythm emphasizing incremental testing
- Feature → Module → Integration → System testing progression
- Professional development standards with student confidence building
This update reflects our actual successful patterns and ensures all future modules follow the proven approaches from our best performing educational content.
🏗️ REPOSITORY RESTRUCTURE:
- Created instructor/ directory with organized subdirectories
- Moved analysis tools to instructor/tools/
- Moved reports to instructor/reports/
- Moved guides to instructor/guides/
- Created docs/ structure for future Quarto documentation
�� NEW STRUCTURE:
- instructor/tools/ - Analysis and utility scripts
- instructor/reports/ - Generated report cards
- instructor/guides/ - Instructor documentation
- instructor/templates/ - Templates and examples
- docs/ - Documentation structure
🔧 FUNCTIONALITY:
- Created analyze_modules.py wrapper for easy access
- Updated paths to work from new locations
- All analysis tools working from reorganized structure
- Comprehensive instructor README with usage guide
✅ VERIFICATION:
- Analysis tools work from root directory
- All modules can be analyzed successfully
- Report generation functions correctly
- Clean, logical directory organization
- Add brief descriptions to YAML frontmatter for all rule files
- Descriptions explain the purpose and content of each rule
- Follow consistent format matching ml-systems-course-context.mdc
- Improve rule discoverability and understanding
Files updated:
- user-preferences.mdc: User preferences and development conventions
- tinytorch-project-structure.mdc: Dual-structure architecture guide
- testing-patterns.mdc: Testing standards with pytest and real data
- nbdev-educational-pattern.mdc: Educational NBDev patterns
- module-development-best-practices.mdc: Real Data, Real Systems principles
- git-workflow.mdc: Git workflow guidelines for incremental commits
- development-workflow.mdc: Complete development workflow with tito CLI
- cli-patterns.mdc: CLI development patterns for tito tool
- Update module → package mapping in pedagogy/vision.md
- Update project guide module references
- Update cursor rules for testing patterns
- Update all documentation paths and references
Ensures all documentation is consistent with the new module name.
Introduces documentation for TinyTorch module development, including guides for developers and AI assistants.
Provides comprehensive resources for creating high-quality, educational modules, focusing on real-world applications and systems thinking.
- Updated git-workflow.mdc with proper metadata and focused content
- Updated development-workflow.mdc with proper metadata
- Added cli-patterns.mdc for CLI development best practices
- Followed Cursor's best practices: focused, actionable, scoped
- Added proper globs for auto-attachment to relevant files
- Improved rule descriptions for better AI context
Key improvements:
- Proper metadata structure with description, globs, alwaysApply
- Focused content under 500 lines per rule
- Concrete examples and patterns
- Clear, actionable guidance for AI
- Better scoping for when rules should apply
- Created comprehensive Git workflow guidelines for ad-hoc development
- Focus on small, focused commits for easy reverts
- Added practical examples for different development scenarios
- Updated development workflow to reference new Git guidelines
- Updated CLI commands to use 'tito' instead of 'python bin/tito.py'
- Includes commit message format, branch strategies, and revert procedures
Key principles:
- Incremental commits for easy reverts
- Test before committing to avoid broken commits
- Use feature branches for larger changes
- Descriptive commit messages that explain what changed
- Add explicit pytest requirement to testing-patterns.mdc
- Update user-preferences.mdc to include pytest preference
- Modify development-workflow.mdc to reference pytest usage
- Specify that all tests must use pytest framework
- Document pytest features to use (classes, fixtures, assertions)
- Add comprehensive examples of proper pytest structure
- Include DO NOT USE section for prohibited testing approaches
- Ensure CLI integration expects pytest-compatible test files
- Make it clear that manual testing and other frameworks are not allowed
- Fix CLI tool to look for tests in modules/{module}/tests/ instead of tests/
- Update test imports to use parent directory module imports
- Update Cursor rules to reflect new test structure:
* Project structure shows tests/ subdirectory
* Testing patterns show correct paths and import patterns
* Development workflow shows updated test locations
- Test imports now work: from tensor_dev import Tensor
- CLI commands now find tests in correct locations
Tests are now properly organized and discoverable
- Fix frontmatter for all rules to include proper descriptions
- Update rule types according to Cursor guidelines:
* alwaysApply: project-structure, user-preferences
* globs: nbdev-educational-pattern, testing-patterns
* description only: development-workflow, ml-systems-course-context
- All rules under 500 lines, focused and actionable
- Follow MDC format with proper metadata
- Ready for proper Cursor rule functionality
- Project structure guide (always applied)
- NBDev educational pattern for module development files
- Development workflow and CLI usage
- Testing patterns and conventions
- ML Systems course context and learning approach
- User preferences and conventions
These rules will help with codebase navigation, understanding the educational approach,
and maintaining consistency across the TinyTorch framework.
