docs(workflow): Clarify TinyTorch development workflow

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
This commit is contained in:
Vijay Janapa Reddi
2025-11-01 14:34:16 -04:00
parent 73adfd1b2e
commit c881ecfe0c

View File

@@ -0,0 +1,102 @@
# Development Workflow Rules
## Branch-First Development
- **Always create a branch** for any work - never work directly on main
- **Branch naming**: `feature/description`, `fix/issue`, `refactor/component`
- **Remind user** to create branches if they forget
## 🚨 CRITICAL: TinyTorch Development Workflow
### The Golden Rule: Source → Export → Use
```
modules/source/ → tito export → tinytorch/ → milestones/
(EDIT HERE!) (BUILD STEP) (NEVER EDIT!) (USE IT!)
```
### Three Sacred Principles
1. **ONLY edit files in `modules/source/`** - This is your source of truth
2. **ALWAYS use `tito export`** to build the `tinytorch/` package
3. **NEVER modify anything in `tinytorch/` directly** - It's generated code!
### Why This Matters
- **`modules/source/`**: Educational module sources (Python `.py` files)
- **`tinytorch/`**: Generated package (like `node_modules/` or `dist/`)
- **`milestones/`**: Student projects that import from `tinytorch`
**If you edit `tinytorch/` directly, your changes will be LOST on next export!**
### Complete Development Workflow
```bash
# 1. Edit the module source (ONLY place to make changes)
vim modules/source/12_attention/attention_dev.py
# 2. Export to tinytorch package (Build step)
tito export
# 3. Test the exported module
pytest tests/12_attention/
# 4. Use in milestones
cd milestones/05_2017_transformer/
python tinytalks_dashboard.py # Uses tinytorch.core.attention
```
## 🚨 CRITICAL: Notebook Development Workflow
**NEVER EDIT .ipynb FILES DIRECTLY**
TinyTorch uses a literate programming approach with nbdev:
1. **Edit ONLY `_dev.py` files** in `modules/source/*/`
2. **Export to tinytorch** using `tito export`
3. **Run tests** with `pytest` to verify changes
4. **Never manually edit .ipynb files** - they are generated artifacts
5. **Never manually edit tinytorch/** - it's generated from modules/source/
### Why This Matters
- `.ipynb` files are JSON and hard to merge/review
- `_dev.py` files are the **source of truth**
- `tinytorch/` is **generated code** (like compiled binaries)
- nbdev ensures proper sync between code, tests, and documentation
- Manual .ipynb edits will be overwritten on next export
- Manual tinytorch/ edits will be overwritten on next export
### Correct Workflow Example
```bash
# 1. Edit the Python source
vim modules/source/12_attention/attention_dev.py
# 2. Export to tinytorch package
tito export
# 3. Run tests
pytest tests/12_attention/
# 4. If tests pass, commit source changes
git add modules/source/12_attention/attention_dev.py
git commit -m "fix(attention): Handle 3D attention masks"
```
## Work Process
1. **Plan**: Define what changes are needed and why
2. **Reason**: Think through the approach and potential issues
3. **Test**: Write tests to verify success before implementing
4. **Execute**: Implement changes in a new Git branch
5. **Verify**: Run all tests and ensure everything works
6. **Merge**: Only merge when fully tested and verified
## Testing Standards
- **Always use pytest** for all tests
- **Test before implementing** - write tests that define success
- **Test after implementing** - verify everything works
- **Test edge cases** and error conditions
## Documentation
- **Prefer Quarto** for documentation generation
- **Keep rules short** and actionable
- **Update rules** as patterns emerge
This ensures quality, traceability, and prevents breaking main branch.