cs249r_book/.github/TINYTORCH_RELEASE_PROCESS.md

TinyTorch Release Process

Overview

This document describes the complete release process for TinyTorch, combining automated CI/CD checks with manual agent-driven reviews.

Release Types

Patch Release (0.1.X)

• Bug fixes
• Documentation updates
• Minor improvements
• Timeline: 1-2 days

Minor Release (0.X.0)

• New module additions
• Feature enhancements
• Significant improvements
• Timeline: 1-2 weeks

Major Release (X.0.0)

• Complete module sets
• Breaking API changes
• Architectural updates
• Timeline: 1-3 months

Two-Track Quality Assurance

Track 1: Automated CI/CD (Continuous)

GitHub Actions runs on every commit and PR:

Every Push/PR:
├── Educational Validation (Module structure, objectives)
├── Implementation Validation (Time, difficulty, tests)
├── Test Validation (All tests, coverage)
├── Package Validation (Builds, installs)
├── Documentation Validation (ABOUT.md, checkpoints)
└── Systems Analysis (Memory, performance, production)

Trigger: Automatic on push/PR

Duration: 15-20 minutes

Pass Criteria: All 6 quality gates green

---

Track 2: Agent-Driven Review (Pre-Release)

Specialized AI agents provide deep review before releases:

TPM Coordinates:
├── Education Reviewer
│   ├── Pedagogical effectiveness
│   ├── Learning objective alignment
│   ├── Cognitive load assessment
│   └── Assessment quality
│
├── Module Developer
│   ├── Implementation standards
│   ├── Code quality patterns
│   ├── Testing completeness
│   └── PyTorch API alignment
│
├── Quality Assurance
│   ├── Comprehensive test validation
│   ├── Edge case coverage
│   ├── Performance testing
│   └── Integration stability
│
└── Package Manager
    ├── Module integration
    ├── Dependency resolution
    ├── Export/import validation
    └── Build verification

Trigger: Manual (via TPM)

Duration: 2-4 hours

Pass Criteria: All agents approve

---

Complete Release Workflow

Phase 1: Development (Ongoing)

1. Feature Development

   • Implement modules following DEFINITIVE_MODULE_PLAN.md
   • Write tests immediately after each function
   • Ensure NBGrader compatibility
   • Add checkpoint markers to long modules

2. Local Validation

   # Run validators locally
   python .github/scripts/validate_time_estimates.py
   python .github/scripts/validate_difficulty_ratings.py
   python .github/scripts/validate_testing_patterns.py
   python .github/scripts/check_checkpoints.py
   
   # Run tests
   pytest tests/ -v
   

3. Commit & Push

   git add .
   git commit -m "feat: Add [feature] to [module]"
   git push origin feature-branch
   

---

Phase 2: Pre-Release Review (1-2 days)

1. Create Release Branch

   git checkout -b release/v0.X.Y
   git push origin release/v0.X.Y
   

2. Automated CI/CD Check

   • GitHub Actions runs automatically
   • Review workflow results
   • Fix any failures

3. Agent-Driven Comprehensive Review

   Invoke TPM for multi-agent review:

   Request to TPM:
   "I need a comprehensive quality review of all 20 TinyTorch modules
   for release v0.X.Y. Please coordinate:
   
   1. Education Reviewer - pedagogical validation
   2. Module Developer - implementation standards
   3. Quality Assurance - testing validation
   4. Package Manager - integration health
   
   Run these in parallel and provide:
   - Consolidated findings report
   - Prioritized action items
   - Estimated effort for fixes
   - Timeline for completion
   
   Release Type: [patch/minor/major]
   Target Date: [YYYY-MM-DD]"
   

4. Review Agent Reports

   • Education Reviewer report
   • Module Developer report
   • Quality Assurance report
   • Package Manager report

5. Address Findings

   • Fix HIGH priority issues immediately
   • Schedule MEDIUM priority for next sprint
   • Document LOW priority as future improvements

---

Phase 3: Release Candidate (1 day)

1. Create Release Candidate

   git tag -a v0.X.Y-rc1 -m "Release candidate 1 for v0.X.Y"
   git push origin v0.X.Y-rc1
   

2. Final Validation

   • Run full test suite
   • Build documentation
   • Test package installation
   • Manual smoke testing

3. Stakeholder Review (if applicable)

   • Share RC with instructors
   • Collect feedback
   • Make final adjustments

---

Phase 4: Release (1 day)

1. Manual Release Check Trigger

   Via GitHub UI:

   • Go to Actions → TinyTorch Release Check
   • Click "Run workflow"
   • Select:
     • Branch: release/v0.X.Y
     • Release Type: [patch/minor/major]
     • Check Level: comprehensive

2. Review Release Report

   • All quality gates pass
   • Download release report artifact
   • Verify all validations green

3. Merge to Main

   git checkout main
   git merge --no-ff release/v0.X.Y
   git push origin main
   

4. Create Official Release

   git tag -a v0.X.Y -m "Release v0.X.Y: [Description]"
   git push origin v0.X.Y
   

5. GitHub Release

   • Go to Releases → Draft a new release
   • Select tag: v0.X.Y
   • Title: TinyTorch v0.X.Y
   • Description: Include release report summary
   • Attach artifacts (wheels, documentation)
   • Publish release

6. Package Distribution

   # Build distribution packages
   python -m build
   
   # Upload to PyPI (if applicable)
   python -m twine upload dist/*
   

---

Phase 5: Post-Release (Ongoing)

1. Documentation Updates

   • Update README.md with new version
   • Update CHANGELOG.md
   • Rebuild Jupyter Book
   • Deploy to mlsysbook.github.io

2. Communication

   • Announce on GitHub
   • Update course materials
   • Notify instructors
   • Social media (if applicable)

3. Monitoring

   • Watch for issues
   • Respond to feedback
   • Plan next release

---

Quality Gates Reference

Must Pass for ALL Releases

✅ All automated CI/CD checks pass ✅ Test coverage ≥80% ✅ All agent reviews approved ✅ Documentation complete ✅ No HIGH priority issues

Additional for Major Releases

✅ All 20 modules validated ✅ Complete integration testing ✅ Performance benchmarks meet targets ✅ Comprehensive stakeholder review

---

Checklist Templates

Patch Release Checklist

## Pre-Release
- [ ] Local validation passes
- [ ] Automated CI/CD passes
- [ ] Bug fix validated
- [ ] Tests updated

## Release
- [ ] Release branch created
- [ ] RC tested
- [ ] Merged to main
- [ ] Tag created
- [ ] GitHub release published

## Post-Release
- [ ] Documentation updated
- [ ] CHANGELOG updated
- [ ] Issue closed

Minor Release Checklist

## Pre-Release
- [ ] All local validations pass
- [ ] Automated CI/CD passes
- [ ] Agent reviews complete (all 4)
- [ ] High priority issues fixed
- [ ] New modules validated
- [ ] Integration tests pass

## Release
- [ ] Release branch created
- [ ] RC tested
- [ ] Stakeholder review (if needed)
- [ ] Merged to main
- [ ] Tag created
- [ ] GitHub release published
- [ ] Package uploaded (if applicable)

## Post-Release
- [ ] Documentation updated
- [ ] CHANGELOG updated
- [ ] Jupyter Book rebuilt
- [ ] Announcement sent

Major Release Checklist

## Pre-Release (1-2 weeks)
- [ ] All local validations pass
- [ ] Automated CI/CD passes
- [ ] Comprehensive agent review (TPM-coordinated)
  - [ ] Education Reviewer approved
  - [ ] Module Developer approved
  - [ ] Quality Assurance approved
  - [ ] Package Manager approved
- [ ] ALL modules validated (20/20)
- [ ] Complete integration testing
- [ ] Performance benchmarks met
- [ ] Documentation complete
- [ ] All HIGH/MEDIUM issues resolved

## Release Candidate (3-5 days)
- [ ] RC1 created and tested
- [ ] Stakeholder feedback collected
- [ ] Final adjustments made
- [ ] RC2 validated (if needed)

## Release
- [ ] Release branch created
- [ ] Comprehensive check run
- [ ] All quality gates green
- [ ] Merged to main
- [ ] Tag created
- [ ] GitHub release published
- [ ] Package uploaded to PyPI
- [ ] Backup created

## Post-Release (1 week)
- [ ] Documentation updated everywhere
- [ ] CHANGELOG complete
- [ ] Jupyter Book rebuilt and deployed
- [ ] All stakeholders notified
- [ ] Social media announcement
- [ ] Course materials updated
- [ ] Monitor for issues

---

Emergency Hotfix Process

For critical bugs in production:

1. Create hotfix branch from main

   git checkout main
   git checkout -b hotfix/v0.X.Y+1
   

2. Fix the issue

   • Minimal changes only
   • Focus on critical bug
   • Add regression test

3. Fast-track validation

   # Quick validation
   python .github/scripts/validate_time_estimates.py
   pytest tests/ -v -k "test_affected_module"
   

4. Release immediately

   git checkout main
   git merge --no-ff hotfix/v0.X.Y+1
   git tag -a v0.X.Y+1 -m "Hotfix: [Description]"
   git push origin main --tags
   

5. Backport to release branches if needed

---

Tools & Resources

GitHub Actions

• Workflow: .github/workflows/release-check.yml
• Scripts: .github/scripts/*.py
• Documentation: .github/workflows/README.md

Agent Coordination

• TPM: .claude/agents/technical-program-manager.md
• Agents: .claude/agents/
• Workflow: DEFINITIVE_MODULE_PLAN.md

Validation

• Time: validate_time_estimates.py
• Difficulty: validate_difficulty_ratings.py
• Tests: validate_testing_patterns.py
• Checkpoints: check_checkpoints.py

---

Version Numbering

TinyTorch follows Semantic Versioning:

Format: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes, complete module sets
• MINOR: New features, module additions
• PATCH: Bug fixes, documentation

Examples:

• 0.1.0 → 0.1.1: Bug fix (patch)
• 0.1.1 → 0.2.0: New module (minor)
• 0.9.0 → 1.0.0: All 20 modules complete (major)

---

Contact & Support

Questions about releases?

• Check this document first
• Review workflow README: .github/workflows/README.md
• Consult TPM agent for complex scenarios
• File issue on GitHub for workflow improvements

---

Last Updated: 2024-11-24 Version: 1.0.0 Maintainer: TinyTorch Team