TinyTorch/docs/development/DEVELOPER_SETUP.md

TinyTorch Developer Setup Guide

Audience: Maintainers, contributors, and developers working on TinyTorch itself

Last Updated: November 27, 2025

---

Quick Start

# Clone and setup
git clone https://github.com/mlsysbook/TinyTorch.git
cd TinyTorch

# Run development setup
./setup-dev.sh

# Activate environment
source .venv/bin/activate

# Verify installation
tito system health

---

Core Development Tools

Required Tools

These are required for TinyTorch development:

# Python 3.9+
python3 --version

# Virtual environment (included in Python)
python3 -m venv --help

# Git
git --version

Recommended Tools

Highly recommended for productive development:

# Code formatting
pip install black isort

# Testing
pip install pytest pytest-cov

# Jupyter (for module development)
pip install jupyter jupyterlab

# Type checking
pip install mypy

---

Optional Tools (by Use Case)

📹 Demo GIF Generation (Maintainers Only)

When you need this: Updating website carousel GIFs when TITO commands change

Install VHS:

# macOS
brew install vhs

# Linux
go install github.com/charmbracelet/vhs@latest

# Verify
vhs --version

Usage:

# Generate all carousel GIFs
./scripts/generate-demo-gifs.sh

# Or individual GIFs
vhs site/_static/demos/tapes/01-zero-to-ready.tape

# Optimize file sizes
./scripts/optimize-gifs.sh

# Validate
./scripts/validate-gifs.sh

Documentation: See site/_static/demos/GIF_PRODUCTION_GUIDE.md

Note: Students never need VHS. This is purely for marketing material generation.

---

📚 Documentation Building

When you need this: Building the Jupyter Book website locally

# Install Jupyter Book
pip install jupyter-book

# Build website
cd site
./build.sh

# Preview
cd _build/html
python -m http.server 8000
open http://localhost:8000

---

🎨 CLI Development

When you need this: Working on TITO commands and Rich UI

# Rich for terminal UI
pip install rich

# Click for CLI framework (already in requirements.txt)
pip install click

# Test CLI commands
tito --help
tito module --help
tito milestones --help

---

Development Workflow

1. Environment Setup

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e .

# Verify
tito --version

2. Making Changes

# Create feature branch
git checkout -b feature/your-feature

# Make changes to code
# Edit files in tito/, tinytorch/, tests/, etc.

# Run tests
pytest tests/

# Format code
black .
isort .

3. Testing Changes

# Test TITO commands
tito system health
tito module status
tito milestones list

# Run specific tests
pytest tests/test_specific.py -v

# Run all tests
pytest tests/ -v --cov=tinytorch

4. Documentation

# Update relevant docs
# - README.md for user-facing changes
# - docs/ for detailed documentation
# - site/ for website content

# Build docs locally
cd site && ./build.sh

5. Committing

# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add new TITO command for xyz"

# Push to your fork
git push origin feature/your-feature

# Create PR on GitHub

---

Project Structure

TinyTorch/
├── tito/                    # TITO CLI commands
│   ├── commands/           # Individual command implementations
│   └── core/               # Core utilities
├── tinytorch/              # TinyTorch package (exported code)
│   └── core/               # Core ML components
├── src/                    # Source modules (student workspace)
│   ├── 01_tensor/
│   ├── 02_activations/
│   └── ...
├── tests/                  # Test suite
│   ├── test_*.py          # Unit tests
│   └── */                 # Module-specific tests
├── modules/                # Generated student notebooks
├── site/                   # Jupyter Book website
│   └── _static/demos/     # Demo GIFs (VHS tapes)
├── scripts/                # Automation scripts
├── docs/                   # Documentation
│   └── development/       # Developer docs (this file)
└── milestones/            # Historical milestone scripts

---

Common Development Tasks

Adding a New TITO Command

1. Create command file: tito/commands/your_command.py
2. Inherit from BaseCommand
3. Implement name, description, add_arguments(), run()
4. Register in tito/commands/__init__.py
5. Test with tito your-command --help
6. Add tests in tests/
7. Update documentation

Creating Demo GIFs

# 1. Update tape file with new commands
vim site/_static/demos/tapes/02-build-test-ship.tape

# 2. Regenerate GIF
vhs site/_static/demos/tapes/02-build-test-ship.tape

# 3. Optimize
./scripts/optimize-gifs.sh

# 4. Validate
./scripts/validate-gifs.sh

# 5. Commit updated GIF
git add site/_static/demos/*.gif
git commit -m "docs: update demo GIFs with new commands"

Updating Module Structure

1. Edit source: src/XX_module/XX_module.py
2. Run export: tito src export XX_module
3. Verify notebook: Check modules/XX_module/
4. Test integration: pytest tests/XX_module/
5. Update docs: src/XX_module/README.md

---

Troubleshooting

VHS Not Found

# Install VHS
brew install vhs  # macOS

# Verify
which vhs
vhs --version

Permission Denied on Scripts

# Make scripts executable
chmod +x scripts/*.sh
chmod +x setup-dev.sh

Import Errors

# Reinstall in development mode
pip install -e .

# Verify
python -c "import tinytorch; print(tinytorch.__version__)"

Tests Failing

# Clean environment
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

# Run tests with verbose output
pytest tests/ -v -s

---

Environment Variables

# Optional: Set for development
export TINYTORCH_DEV=1              # Enable dev features
export TINYTORCH_DEBUG=1            # Verbose logging
export TINYTORCH_TEST_MODE=1        # Skip slow operations in tests

---

Git Workflow

Branch Naming

feature/add-new-command       # New features
fix/bug-in-export            # Bug fixes
docs/update-readme           # Documentation
refactor/cleanup-tests       # Code refactoring
perf/optimize-loading        # Performance improvements

Commit Messages

Follow conventional commits:

feat: add new milestone command
fix: resolve export bug in tensor module
docs: update developer setup guide
test: add integration tests for autograd
refactor: simplify CLI argument parsing
perf: optimize GIF generation script

---

Release Checklist

When preparing a release:

• All tests pass: pytest tests/
• Documentation updated: site/, README.md, CHANGELOG.md
• Demo GIFs current: Check TITO commands match
• Version bumped: setup.py, __init__.py
• Git tag created: git tag v1.0.0
• Release notes written
• PyPI package updated (if applicable)

---

Getting Help

For Development Questions:

• Check existing issues: https://github.com/mlsysbook/TinyTorch/issues
• Review documentation: docs/ directory
• Ask in discussions: GitHub Discussions

For CLI Development:

• See: docs/development/CLI_TEST_PLAN.md
• See: docs/development/CLI_VISUAL_DESIGN.md

For GIF Production:

• See: site/_static/demos/GIF_PRODUCTION_GUIDE.md
• See: site/_static/demos/QUICK_START.md

---

Contributing

See CONTRIBUTING.md for:

• Code style guidelines
• Testing requirements
• PR submission process
• Code review expectations

---

Remember: Students never need to install VHS or other dev tools. They just need Python, the TinyTorch environment, and Jupyter. All dev tooling is optional and for maintainers only.