diff --git a/binder b/binder index 168b400c2..8cdf03107 100755 --- a/binder +++ b/binder @@ -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( diff --git a/docs/RELEASE_PROCESS.md b/docs/RELEASE_PROCESS.md new file mode 100644 index 000000000..1772d7074 --- /dev/null +++ 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 \ No newline at end of file diff --git a/quarto/_quarto.yml b/quarto/_quarto.yml index 40e97aabe..ec64ecf41 120000 --- a/quarto/_quarto.yml +++ b/quarto/_quarto.yml @@ -1 +1 @@ -config/_quarto-pdf.yml \ No newline at end of file +config/_quarto-html.yml \ No newline at end of file