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

```bash
# 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:

```bash
# Python 3.9+
python3 --version

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

# Git
git --version
```

### Recommended Tools

Highly recommended for productive development:

```bash
# 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:**

```bash
# macOS
brew install vhs

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

# Verify
vhs --version
```

**Usage:**

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Install VHS
brew install vhs  # macOS

# Verify
which vhs
vhs --version
```

### Permission Denied on Scripts

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

### Import Errors

```bash
# Reinstall in development mode
pip install -e .

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

### Tests Failing

```bash
# 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

```bash
# 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.