Merge branch 'main' of https://github.com/harvard-edge/cs249r_book

2026-03-11 17:49:25 -05:00 · 2025-08-05 21:23:34 -04:00
parent c915c5e347 510a0cf768
commit ea980d996b
3 changed files with 317 additions and 15 deletions
--- a/103
+++ b/103
@@ -1198,6 +1198,71 @@ class BookBinder:
    # 🚀 Enhanced Publishing Methods
    # ═══════════════════════════════════════════════════════════════════════════
    
+    def _show_publish_header(self):
+        """Display header for website publishing"""
+        console.print()
+        banner = Panel(
+            "[bold blue]📚 Website Publisher[/bold blue]\n\n"
+            "[cyan]Deploy latest content to GitHub Pages[/cyan]\n"
+            "[dim]• Builds HTML + PDF\n"
+            "• Updates https://mlsysbook.ai\n"
+            "• No versioning or releases[/dim]",
+            title="🌐 Binder Publish",
+            border_style="blue",
+            padding=(1, 2)
+        )
+        console.print(banner)
+        console.print()
+
+    def _show_release_header(self):
+        """Display header for formal releases"""
+        console.print()
+        banner = Panel(
+            "[bold green]🏷️  Release Manager[/bold green]\n\n"
+            "[yellow]Create formal textbook releases[/yellow]\n"
+            "[dim]• Semantic versioning\n"
+            "• Git tags & GitHub releases\n"
+            "• Academic citations ready[/dim]",
+            title="📦 Binder Release",
+            border_style="green",
+            padding=(1, 2)
+        )
+        console.print(banner)
+        console.print()
+
+    def _validate_git_status_for_publish(self):
+        """Relaxed git validation for website publishing"""
+        try:
+            # Check if we're in a git repo
+            result = subprocess.run(['git', 'status', '--porcelain'], 
+                                  capture_output=True, text=True, cwd=self.root_dir)
+            if result.returncode != 0:
+                console.print("[red]❌ Not in a valid git repository[/red]")
+                return False
+            
+            # For publishing, we allow uncommitted changes (just warn)
+            if result.stdout.strip():
+                console.print("[yellow]⚠️  You have uncommitted changes.[/yellow]")
+                console.print("[dim]Website will be built from committed content only.[/dim]")
+                console.print()
+            
+            return True
+        except Exception as e:
+            console.print(f"[red]❌ Git validation failed: {e}[/red]")
+            return False
+
+    def _show_publish_website_success(self):
+        """Show success message for website publishing"""
+        console.print()
+        console.print("[bold green]🎉 Website Successfully Deployed![/bold green]")
+        console.print()
+        console.print("[bold white]📋 Access Your Updated Website:[/bold white]")
+        console.print("[blue]   🌐 Website: https://mlsysbook.ai[/blue]")
+        console.print("[blue]   📄 PDF: https://mlsysbook.ai/assets/Machine-Learning-Systems.pdf[/blue]")
+        console.print()
+        console.print("[dim]💡 Changes may take a few minutes to appear due to caching[/dim]")
+        console.print("[green]✅ Ready for students and educators![/green]")
+
    def _show_publisher_header(self):
        """Display the publisher header with prominent warning"""
        # Big red warning box
@@ -1412,13 +1477,18 @@ class BookBinder:
            console.print(f"[blue]ℹ️  Current version: {current_version}[/blue]")
            console.print()
            
-            # Show version type guide
-            console.print("[bold white]📋 Version Type Guide:[/bold white]")
-            console.print("[green]  1. patch[/green]   - Bug fixes, typos, small corrections      (v1.0.0 → v1.0.1)")
-            console.print("[yellow]  2. minor[/yellow]   - New content, features, improvements     (v1.0.0 → v1.1.0)")
-            console.print("[red]  3. major[/red]   - Breaking changes, major restructuring   (v1.0.0 → v2.0.0)")
+            # Show version type guide (textbook-specific)
+            console.print("[bold white]📋 Textbook Release Type Guide:[/bold white]")
+            console.print("[green]  1. patch[/green]   - Typos, corrections, minor fixes          (v1.0.0 → v1.0.1)")
+            console.print("[yellow]  2. minor[/yellow]   - New chapters, labs, major content       (v1.0.0 → v1.1.0)")
+            console.print("[red]  3. major[/red]   - Complete restructuring, new edition     (v1.0.0 → v2.0.0)")
            console.print("[blue]  4. custom[/blue]  - Specify your own version number")
            console.print()
+            console.print("[dim]💡 Examples:[/dim]")
+            console.print("[dim]   • Patch: Fixed equations in Chapter 8, corrected references[/dim]")
+            console.print("[dim]   • Minor: Added new \"Federated Learning\" chapter[/dim]")
+            console.print("[dim]   • Major: Restructured entire book for new academic year[/dim]")
+            console.print()
            
            console.print("[white]What type of changes are you publishing?[/white]")
            console.print("[white]Select option [1-4] [default: 2 for minor]: [/white]", end="")
@@ -2508,8 +2578,8 @@ This release includes the following changes:
            
            console.print(f"[blue]ℹ️  Using AI model: {model}[/blue]")
            
-            # Create AI prompt
-            prompt = f"""Please create professional release notes for version {version} based on the following git commits.
+            # Create AI prompt tailored for academic textbook
+            prompt = f"""Please create professional release notes for version {version} of the Machine Learning Systems textbook based on the following git commits.

 Release Description: {description}
 Release Type: minor
@@ -2517,13 +2587,18 @@ Release Type: minor
 Git Commits:
 {git_changes}

-Please format as:
- Brief overview of this release
- Key changes organized by category (Features, Bug Fixes, Improvements, etc.)
- Keep it professional but accessible
- Include any breaking changes if evident
- Do not include the git commit hashes or technical details
- Focus on user-facing changes and improvements"""
+This is an ACADEMIC TEXTBOOK release. Please format as:
+- Brief overview of this release for students and educators
+- Key changes organized by category:
+  * 📚 New Content (chapters, sections, concepts)
+  * 🔧 Improvements (clarity, examples, explanations)
+  * 🐛 Fixes (typos, errors, broken links)
+  * 🎯 Enhancements (figures, exercises, references)
+- Focus on educational value and learning outcomes
+- Mention any new chapters, lab exercises, or major content additions
+- Keep it professional but accessible to students
+- Do not include technical git details or development-specific changes
+- Emphasize content that benefits learning ML systems concepts"""

            # Generate AI summary with timeout
            with Progress(
--- a/docs/RELEASE_PROCESS.md
+++ b/docs/RELEASE_PROCESS.md
@@ -0,0 +1,227 @@
+# Release Process for MLSysBook
+
+## 🎯 Release Strategy
+
+We follow a milestone-based release approach suitable for an academic textbook project.
+
+## 📋 Release Types
+
+### Major Releases (x.0.0)
+- Complete textbook releases
+- Major structural changes
+- Significant content overhauls
+- **Frequency:** Semester/annual
+
+### Minor Releases (x.y.0)
+- New chapters added
+- New lab exercises
+- Significant content additions
+- **Frequency:** Monthly or per major feature
+
+### Patch Releases (x.y.z)
+- Bug fixes and typos
+- Minor content updates
+- Formatting improvements
+- **Frequency:** As needed
+
+## 🔄 Daily Workflow
+
+### For Regular Development (Website Updates)
+```bash
+# 1. Make changes on feature branches
+git checkout -b feature/new-chapter
+
+# 2. Commit and push changes
+git add .
+git commit -m "feat(chapter): add new optimization techniques chapter"
+git push origin feature/new-chapter
+
+# 3. Create PR and merge to main
+# (GitHub PR process)
+
+# 4. Deploy to website (no formal release)
+./binder publish     # Quick website deployment
+```
+
+### For Formal Releases (Milestones)
+```bash
+# 1. Ensure main is up to date
+git checkout main
+git pull origin main
+
+# 2. Create formal release with versioning
+./binder release
+
+# 3. Follow interactive prompts for:
+#    - Semantic version type (patch/minor/major)  
+#    - Release description
+#    - Git tag creation
+#    - GitHub release with PDF attachment
+```
+
+## 🏷️ Versioning Guidelines
+
+### Version Number Format: `vMAJOR.MINOR.PATCH`
+
+**Examples:**
+- `v1.0.0` - First complete textbook release
+- `v1.1.0` - Added new "Federated Learning" chapter
+- `v1.1.1` - Fixed typos and updated references
+- `v2.0.0` - Major restructuring with new part organization
+
+### When to Increment:
+
+**MAJOR** (x.0.0):
+- Complete textbook restructuring
+- Breaking changes to existing content organization
+- Major pedagogical approach changes
+
+**MINOR** (x.y.0):
+- New chapters or major sections
+- New lab exercises or projects
+- Significant content additions (>10% new material)
+
+**PATCH** (x.y.z):
+- Bug fixes, typos, formatting
+- Minor content updates (<5% changes)
+- Reference updates, link fixes
+
+## 📝 Release Notes
+
+### Automated Generation
+- Use `./binder release` for AI-generated release notes
+- Always review and edit before publishing
+- Include:
+  - Overview of changes
+  - New content highlights
+  - Bug fixes and improvements
+  - Any breaking changes
+
+### Manual Release Notes Template
+```markdown
+# Release v1.1.0: New Optimization Techniques
+
+## 🆕 New Content
+- Added Chapter 12: Advanced Optimization Techniques
+- New lab exercise on hyperparameter tuning
+- Extended bibliography with 50+ new references
+
+## 🐛 Bug Fixes
+- Fixed equation formatting in Chapter 8
+- Corrected code examples in PyTorch section
+
+## 🔧 Improvements
+- Updated all Python code examples to Python 3.11
+- Improved figure quality and accessibility
+- Enhanced cross-references throughout
+
+## 📊 Statistics
+- Total pages: 450 (+25 from previous version)
+- New exercises: 12
+- Updated figures: 8
+```
+
+## 🚀 Deployment Strategy
+
+### Two-Tier Publishing System
+
+#### Website Publishing (`./binder publish`)
+- **Purpose:** Quick content updates for daily development
+- **Process:** Builds HTML + PDF, deploys to GitHub Pages
+- **Requirements:** Minimal git validation (allows uncommitted changes)
+- **Result:** Updates https://mlsysbook.ai immediately
+- **No Versioning:** No git tags or formal releases created
+
+#### Formal Releases (`./binder release`)  
+- **Purpose:** Academic milestones and citation-ready releases
+- **Process:** Semantic versioning + GitHub release creation
+- **Requirements:** Clean git state, intentional versioning decisions
+- **Result:** Tagged releases with attached PDFs for citations
+- **Versioning:** Git tags, release notes, academic distribution
+
+### Deployment Locations
+- **Live Website:** https://mlsysbook.ai (updated by `publish`)
+- **PDF Download:** https://mlsysbook.ai/assets/Machine-Learning-Systems.pdf
+- **Tagged Releases:** https://github.com/harvard-edge/cs249r_book/releases
+- **Versioned PDFs:** Attached to each GitHub release for citations
+
+## 🛡️ Best Practices
+
+### Before Creating a Release
+1. **Content Review:**
+   - Proofread new content
+   - Verify all links and references
+   - Test all code examples
+   - Check figure quality and captions
+
+2. **Technical Checks:**
+   - Run `./binder build` to ensure clean build
+   - Verify PDF generation works
+   - Check website deployment
+   - Run pre-commit hooks
+
+3. **Documentation:**
+   - Update CHANGELOG.md
+   - Review and update README if needed
+   - Ensure release notes are comprehensive
+
+### Release Timing
+- **Avoid:** Releases during exam periods or holidays
+- **Prefer:** Beginning of week for better visibility
+- **Coordinate:** With course schedules if used in classes
+
+### Communication
+- Announce major releases via:
+  - GitHub release notifications
+  - Course announcements (if applicable)
+  - Social media/academic networks
+  - Email to collaborators
+
+## 🔄 Maintenance Releases
+
+For critical fixes between planned releases:
+
+```bash
+# Create hotfix branch
+git checkout -b hotfix/critical-bug-fix
+
+# Make minimal fix
+git commit -m "fix: critical typo in equation 8.3"
+
+# Create patch release
+./binder release  # Will suggest next patch version
+```
+
+## 📋 Release Checklist
+
+### Pre-Release
+- [ ] All content reviewed and proofread
+- [ ] All code examples tested
+- [ ] Links and references verified
+- [ ] Clean build successful (`./binder build`)
+- [ ] PDF generation working
+- [ ] No linting errors
+- [ ] CHANGELOG.md updated
+
+### Release Process
+- [ ] Created release branch if needed
+- [ ] Generated and reviewed release notes
+- [ ] Tagged with semantic version
+- [ ] GitHub release published
+- [ ] PDF attached to release
+- [ ] Website deployed and verified
+
+### Post-Release
+- [ ] Release announcement sent
+- [ ] Social media updates (if applicable)
+- [ ] Course materials updated (if applicable)
+- [ ] Next release planning initiated
+
+---
+
+## 📞 Questions?
+
+For questions about the release process, see:
+- `./binder help` for tool-specific guidance
+- GitHub Issues for process improvements
+- CONTRIBUTING.md for development workflow
--- a/quarto/_quarto.yml
+++ b/quarto/_quarto.yml
@@ -1 +1 @@
-config/_quarto-pdf.yml
+config/_quarto-html.yml