mirror of
https://github.com/MLSysBook/TinyTorch.git
synced 2026-04-28 18:00:02 -05:00
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:
102
.cursor/rules/development-workflow.md
Normal file
102
.cursor/rules/development-workflow.md
Normal 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.
|
||||
Reference in New Issue
Block a user