github-starred/cs249r_book
2
0
Fork 0
mirror of https://github.com/harvard-edge/cs249r_book.git synced 2026-04-29 00:59:07 -05:00
Code Issues 77 Packages Projects Releases 24 Wiki Activity

Removes learning objectives framework

Browse Source 
Removes the learning objectives framework, part key validation system, and the publish live workflow documentation.

These files are being removed to facilitate a reorganization of the project's documentation structure and workflows.
This commit is contained in:
Vijay Janapa Reddi
2026-01-07 11:57:35 -05:00
parent c60ac38ef3
commit 9a44d0ea16
3 changed files with 38 additions and 850 deletions
Download Patch File Download Diff File Expand all files Collapse all files

504
book/docs/LEARNING_OBJECTIVES_FRAMEWORK.md
View File

@@ -1,504 +0,0 @@
# Learning Objectives and Assessment Alignment Framework
**Version:** 1.0
**Created:** 2025-11-01
**Purpose:** Establish systematic framework for aligning chapter learning objectives with quiz assessments across all 21 chapters
---
## Framework Overview
This document establishes the systematic framework for ensuring pedagogical validity through explicit alignment between:
1. Chapter-level learning objectives
2. Section-level content coverage
3. Quiz question assessments
4. Student learning outcomes
### Design Principles
1. **Traceability**: Every quiz question maps to specific learning objective(s)
2. **Measurability**: Each objective has clear, assessable outcomes
3. **Consistency**: Similar cognitive levels use similar assessment approaches
4. **Completeness**: All objectives are adequately assessed
5. **Balance**: Assessment coverage matches objective emphasis
---
## I. Learning Objective Standards
### A. Structural Requirements
**Per Chapter:**
- **Count**: 6-8 learning objectives (7±1 guideline)
- **Length**: Maximum 20-25 words per objective
- **Format**: Bullet list with consistent structure
**Part-Specific Targets:**
| Part | Chapters | Objective Count | Focus |
|------|----------|----------------|-------|
| I: Foundations | 1-5 | 6-7 | Foundational concepts |
| II: Core Engineering | 6-12 | 7-8 | Systems implementation |
| III: Deployment | 13-14 | 7-8 | Operational practices |
| IV: Trustworthy AI | 15-19 | 7-8 | Robustness and ethics |
| V: Future | 20-21 | 7-8 | Synthesis and frontiers |
### B. Bloom's Taxonomy Mapping
**Required Cognitive Verbs by Part:**
**Part I (Foundations):**
- Remember: Define, Identify, List, Recall, Recognize
- Understand: Explain, Describe, Distinguish, Compare, Trace
- Apply: Apply, Calculate, Demonstrate, Implement
**Part II-III (Core/Deployment):**
- Analyze: Analyze, Differentiate, Examine, Classify
- Evaluate: Evaluate, Assess, Critique, Judge, Compare
- Create: Design, Construct, Develop, Formulate
**Part IV-V (Advanced/Synthesis):**
- High-level Evaluate: Critique using frameworks, Assess trade-offs
- High-level Create: Synthesize, Integrate, Design novel solutions
### C. Objective Template
```markdown
[Bloom's Verb] [specific concept/technique/system] [optional: using/based on X] [optional: to achieve Y]
```
**Good Examples:**
```markdown
✓ "Analyze scaling law relationships to determine optimal resource allocation strategies"
✓ "Design fault tolerance strategies combining hardware and software protection"
✓ "Evaluate trade-offs between precision levels and accuracy, energy, hardware compatibility"
```
**Poor Examples:**
```markdown
✗ "Understand machine learning systems" (vague verb)
✗ "Learn about optimization techniques for neural networks in various deployment contexts" (too long, vague)
✗ "Explore different approaches" (not measurable)
```
### D. Specificity Guidelines
**When to be specific:**
- Tools/Frameworks: Name specific tools when chapter teaches them (e.g., "using Fairlearn", "MLPerf benchmarks")
- Metrics: Include specific metrics when chapter focuses on them (e.g., "including throughput, latency, energy")
- Quantities: Add numbers when pedagogically valuable (e.g., "3-5× memory overhead")
**When to be general:**
- Foundational chapters: Remain tool-agnostic
- Conceptual sections: Focus on principles over implementations
- Rapidly evolving areas: Use "such as" qualifiers
---
## II. Quiz Alignment Standards
### A. Question-to-Objective Mapping
**Coverage Requirements:**
| Objective Bloom Level | Minimum Questions | Question Types |
|----------------------|-------------------|----------------|
| Remember/Understand | 2-3 | MCQ, TF, FILL |
| Apply | 3-4 | MCQ, SHORT, ORDER |
| Analyze/Evaluate | 3-5 | SHORT, MCQ (complex) |
| Create/Synthesize | 2-3 | SHORT (scenarios) |
**Total per chapter:** 30-50 quiz questions across all sections
### B. Quiz Objective Format
**Current Practice (Inconsistent):**
```json
"learning_objective": "Understand the fundamental difference..."
```
**New Standard:**
```json
"learning_objective": "LO-1: Define machine learning systems as integrated computing systems",
"chapter_objective_id": "intro-obj-1",
"bloom_level": "Remember",
"cognitive_level": "Foundational"
```
### C. Question Type Alignment
**By Bloom Level:**
| Cognitive Level | Appropriate Question Types | Examples |
|----------------|---------------------------|----------|
| Remember | MCQ (recall), TF, FILL | "What is the primary lesson from Sutton's Bitter Lesson?" |
| Understand | MCQ (comprehension), SHORT (explain) | "Explain how the AI Triad framework helps..." |
| Apply | SHORT (scenario), ORDER (sequence) | "In a production system, how might you address..." |
| Analyze | SHORT (compare/contrast), MCQ (complex) | "Analyze how data drift affects performance..." |
| Evaluate | SHORT (critique/assess) | "Evaluate the trade-offs between..." |
| Create | SHORT (design/propose) | "Design a fault tolerance strategy for..." |
---
## III. Mapping Schema
### A. Master Alignment File Structure
**Location:** `/docs/learning_objectives/`
**File naming:** `{chapter_name}_objectives_mapping.json`
**Schema:**
```json
{
"metadata": {
"chapter": "introduction",
"chapter_number": 1,
"part": "I: Foundations",
"version": "1.0",
"last_updated": "2025-11-01",
"total_objectives": 9,
"total_quiz_questions": 40,
"coverage_complete": true
},
"learning_objectives": [
{
"id": "intro-obj-1",
"order": 1,
"text": "Define machine learning systems as integrated computing systems comprising data, algorithms, and infrastructure",
"bloom_verb": "Define",
"bloom_level": "Remember",
"cognitive_domain": "Factual Knowledge",
"key_concepts": ["ML systems", "data-algorithm-infrastructure triangle", "system integration"],
"sections": ["#sec-introduction-defining-ml-systems-bf7d"],
"page_range": "15-20",
"quiz_questions": [
{
"question_id": "intro-q1",
"section_id": "#sec-introduction-defining-ml-systems-bf7d",
"question_type": "MCQ",
"question_text": "Which of the following best describes a machine learning system?",
"bloom_level": "Remember",
"alignment_quality": "direct"
},
{
"question_id": "intro-q2",
"section_id": "#sec-introduction-defining-ml-systems-bf7d",
"question_type": "SHORT",
"question_text": "Explain how the concept of 'silent performance degradation'...",
"bloom_level": "Understand",
"alignment_quality": "indirect"
}
],
"assessment_coverage": {
"total_questions": 4,
"by_type": {
"MCQ": 2,
"SHORT": 2,
"TF": 0
},
"adequate": true
}
}
],
"validation": {
"all_objectives_assessed": true,
"coverage_gaps": [],
"over_assessed_objectives": [],
"unmapped_questions": []
}
}
```
### B. Alignment Quality Levels
| Quality Level | Definition | Action Required |
|--------------|------------|-----------------|
| **direct** | Question directly assesses stated objective | None ✓ |
| **indirect** | Question assesses related concept supporting objective | Review alignment |
| **partial** | Question partially addresses objective | Add complementary questions |
| **weak** | Minimal connection to objective | Revise question or objective |
| **none** | No clear connection | Remove or map elsewhere |
---
## IV. Validation Rules
### A. Objective-Level Validation
**Rule 1: Coverage Completeness**
```
ASSERT: Each objective has >= 2 quiz questions
SEVERITY: Error
```
**Rule 2: Bloom Level Consistency**
```
ASSERT: Question Bloom level <= Objective Bloom level + 1
SEVERITY: Warning
EXAMPLE: "Define X" objective shouldn't have "Synthesize" questions
```
**Rule 3: Assessment Balance**
```
ASSERT: No objective has >40% of chapter's quiz questions
SEVERITY: Warning
RATIONALE: Suggests over-emphasis or too-broad objective
```
### B. Quiz-Level Validation
**Rule 4: Question Mapping**
```
ASSERT: Every quiz question maps to at least one learning objective
SEVERITY: Error
```
**Rule 5: Learning Objective Consistency**
```
ASSERT: Quiz JSON "learning_objective" field matches mapped chapter objective
SEVERITY: Error
```
**Rule 6: Section Alignment**
```
ASSERT: Quiz question section_id matches objective section_id
SEVERITY: Warning
```
### C. Chapter-Level Validation
**Rule 7: Objective Count**
```
ASSERT: 6 <= objective_count <= 8
SEVERITY: Warning
```
**Rule 8: Bloom Distribution**
```
ASSERT: Chapter includes objectives from at least 3 Bloom levels
SEVERITY: Warning
RATIONALE: Ensures cognitive progression
```
**Rule 9: Question Density**
```
ASSERT: 30 <= total_questions <= 50
SEVERITY: Warning
```
---
## V. Implementation Process
### Phase 1: Foundation (Chapters 1-5)
**For each chapter:**
1. Extract current learning objectives from `.qmd` file
2. Extract quiz questions from `*_quizzes.json` file
3. Create mapping file using schema above
4. Identify misalignments and gaps
5. Revise objectives OR quiz questions as needed
6. Validate using rules above
### Phase 2: Core Engineering (Chapters 6-14)
**Focus areas:**
- Ensure implementation objectives have practical questions
- Verify tool-specific objectives have hands-on assessments
- Check systems trade-off objectives have scenario questions
### Phase 3: Advanced Topics (Chapters 15-21)
**Focus areas:**
- Ensure synthesis objectives have integrative questions
- Verify critique objectives have evaluation scenarios
- Check design objectives have open-ended assessments
### Phase 4: Global Validation
1. Generate cross-chapter alignment report
2. Check prerequisite chains
3. Validate cognitive progression across parts
4. Ensure no concept gaps or overlaps
---
## VI. Maintenance Guidelines
### A. When Objectives Change
**Checklist:**
- [ ] Update chapter `.qmd` file
- [ ] Update mapping JSON file
- [ ] Review affected quiz questions
- [ ] Run validation suite
- [ ] Update quiz JSON `learning_objective` fields
### B. When Quiz Questions Change
**Checklist:**
- [ ] Verify question still maps to objective
- [ ] Update mapping JSON if needed
- [ ] Check coverage requirements still met
- [ ] Run validation suite
- [ ] Update quiz JSON metadata
### C. Annual Review Process
**Q3 each year:**
1. Review all mappings for curriculum updates
2. Check for emerging topics needing new objectives
3. Assess quiz question quality and difficulty
4. Update Bloom taxonomy applications
5. Revise documentation as needed
---
## VII. Tooling Support
### A. Validation Script
**Location:** `/tools/scripts/content/validate_learning_objectives.py`
**Usage:**
```bash
python validate_learning_objectives.py --chapter introduction
python validate_learning_objectives.py --all
python validate_learning_objectives.py --report
```
**Outputs:**
- Validation report (errors/warnings)
- Coverage analysis
- Alignment quality metrics
- Suggested improvements
### B. Mapping Generator
**Location:** `/tools/scripts/content/generate_objective_mapping.py`
**Usage:**
```bash
python generate_objective_mapping.py --chapter introduction --output docs/learning_objectives/
```
**Functionality:**
- Parses `.qmd` for objectives
- Parses `*_quizzes.json` for questions
- Generates initial mapping structure
- Identifies obvious gaps
### C. Sync Tool
**Location:** `/tools/scripts/content/sync_objectives.py`
**Usage:**
```bash
python sync_objectives.py --chapter introduction --dry-run
python sync_objectives.py --chapter introduction --apply
```
**Functionality:**
- Updates quiz JSON `learning_objective` fields
- Ensures consistency across files
- Generates diff report
---
## VIII. Success Metrics
### A. Quantitative Metrics
| Metric | Target | Current (Baseline) |
|--------|--------|-------------------|
| Objectives with adequate coverage | 100% | TBD |
| Quiz questions mapped to objectives | 100% | ~60% |
| Chapters with 6-8 objectives | 100% | ~85% |
| Alignment quality (direct/indirect) | >90% | TBD |
| Validation errors | 0 | TBD |
### B. Qualitative Indicators
- [ ] Student feedback indicates clear understanding of expectations
- [ ] Quiz performance matches objective difficulty levels
- [ ] Instructors can easily customize objective subsets
- [ ] External reviewers assess objectives as "exemplary"
---
## IX. Examples and Anti-Patterns
### A. Exemplary Alignment
**Chapter:** On-Device Learning
**Objective:** "Analyze how training amplifies resource constraints compared to inference, quantifying memory (3-5×), computational (2-3×), and energy overhead impacts"
**Mapped Questions:**
1. MCQ: "What is the typical memory overhead for on-device training compared to inference?" (Remember)
2. SHORT: "Explain why training requires 2-3× more computation than inference in on-device scenarios" (Understand)
3. SHORT: "Analyze how these resource constraints affect your choice of training algorithm for a mobile device" (Analyze)
**Why it works:**
- Specific quantities in objective enable factual questions
- Progressive Bloom levels in questions
- Adequate coverage (3 questions for complex objective)
### B. Poor Alignment (Anti-Pattern)
**Chapter:** Introduction (Original)
**Objective:** "Define machine learning systems as integrated computing systems comprising data, algorithms, and infrastructure"
**Original Quiz Objective:** "Understand the fundamental difference between traditional and ML systems."
**Problems:**
1. Different verb ("Define" vs "Understand")
2. Different focus (ML system definition vs comparison)
3. Lower specificity in quiz version
4. No mention of data-algorithm-infrastructure
**Fix:**
- Revise quiz objective to: "Define ML systems' three core components and their integration"
- OR revise chapter objective to: "Distinguish ML systems from traditional software through architectural comparison"
---
## X. References and Resources
### Academic Foundation
1. Bloom, B.S. (1956). *Taxonomy of Educational Objectives*
2. Anderson, L.W., & Krathwohl, D.R. (2001). *Taxonomy for Learning, Teaching, and Assessing*
3. Wiggins, G., & McTighe, J. (2005). *Understanding by Design*
### Assessment Best Practices
1. Constructive alignment principles (Biggs & Tang, 2011)
2. Evidence-centered design (Mislevy et al., 2003)
3. Validity frameworks (Messick, 1995)
### ML Education Specific
1. ACM/IEEE CS2023 Curricula Guidelines
2. MLOps Maturity Models
3. AI Engineering Education Framework (2024)
---
## XI. Version History
| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 1.0 | 2025-11-01 | Initial framework creation | Editorial Review Team |
---
## Contact and Contributions
**Questions:** Open issue on GitHub with tag `learning-objectives`
**Improvements:** Submit PR to `/docs/LEARNING_OBJECTIVES_FRAMEWORK.md`
**Review Cycle:** Quarterly updates aligned with book releases
---
*This framework establishes MLSysBook as the gold standard for pedagogically rigorous technical textbooks with evidence-based learning design.*

167
book/docs/PART_KEY_VALIDATION.md
View File

@@ -2,22 +2,22 @@
## Overview
The part key validation system ensures that all `\part{key:xxx}` commands in your `.qmd` files reference valid keys defined in `quarto/part_summaries.yml`. This prevents build failures and ensures consistent part titles throughout your book.
The part key validation system ensures that all `\part{key:xxx}` commands in your `.qmd` files reference valid keys defined in `quarto/contents/parts/summaries.yml`. This prevents build failures and ensures consistent part titles throughout your book.
## How It Works
### 1. Pre-Scan Validation (Lua Filter)
The `config/lua/inject-parts.lua` filter now includes a pre-scan step that:
The `quarto/filters/inject_parts.lua` filter includes a pre-scan step that:
- **Scans the entire document** before processing any blocks
- **Validates all keys** against `part_summaries.yml`
- **Validates all keys** against `summaries.yml`
- **Reports issues immediately** with detailed error messages
- **Stops the build** if any invalid keys are found
### 2. Standalone Validation Script
The `scripts/validate_part_keys.py` script provides:
The `tools/scripts/utilities/validate_part_keys.py` script provides:
- **Independent validation** without running the full build
- **Comprehensive reporting** of all issues
@@ -40,49 +40,32 @@ git commit -m "Your commit message"
### Manual Validation
```bash
# Run pre-commit manually
pre-commit run validate-part-keys --all-files
# Or run the validation script directly
python3 scripts/validate_part_keys.py
# Run the validation script from the book directory
python3 tools/scripts/utilities/validate_part_keys.py
# Or use the wrapper script
./scripts/check_keys.sh
```
### Pre-commit Installation
If you haven't installed pre-commit hooks yet:
```bash
# Install pre-commit hooks
pre-commit install
# Run all hooks on existing files
pre-commit run --all-files
./tools/scripts/check_keys.sh
```
## Available Keys
The following keys are defined in `quarto/part_summaries.yml`:
The following keys are defined in `quarto/contents/parts/summaries.yml`:
| Key | Title | Type |
|-----|-------|------|
| `frontmatter` | Frontmatter | Division |
| `main_content` | Main Content | Division |
| `foundations` | Foundations | Part |
| `principles` | Design Principles | Part |
| `optimization` | Performance Engineering | Part |
| `deployment` | Robust Deployment | Part |
| `trustworthy` | Trustworthy Systems | Part |
| `futures` | ML Systems Frontiers | Part |
| `labs` | Labs | Division |
| `arduino` | Arduino Labs | Lab |
| `xiao` | Seeed XIAO Labs | Lab |
| `grove` | Grove Vision Labs | Lab |
| `raspberry` | Raspberry Pi Labs | Lab |
| `shared` | Shared Labs | Lab |
| `backmatter` | Backmatter | Division |
| `volume_1` | Volume I: Introduction to ML Systems | Division |
| `vol1_foundations` | ML Foundations | Part |
| `vol1_development` | System Development | Part |
| `vol1_optimization` | Model Optimization | Part |
| `vol1_operations` | System Operations | Part |
| `volume_2` | Volume II: Advanced ML Systems | Division |
| `vol2_scale` | Foundations of Scale | Part |
| `vol2_distributed` | Distributed Systems | Part |
| `vol2_production` | Production Challenges | Part |
| `vol2_responsible` | Responsible Deployment | Part |
| `backmatter` | References | Division |
| `references` | Bibliography | Lab |
## Error Handling
@@ -91,12 +74,12 @@ The following keys are defined in `quarto/part_summaries.yml`:
When the Lua filter encounters an invalid key:
```
❌ CRITICAL ERROR: UNDEFINED KEY 'invalid_key' not found in part_summaries.yml
❌ CRITICAL ERROR: UNDEFINED KEY 'invalid_key' not found in summaries.yml
📍 Location: RawBlock processing
🔍 DEBUG: Key 'invalid_key' found in RawBlock
📍 RawBlock content: \part{key:invalid_key}
📍 RawBlock format: latex
🔍 Available keys: frontmatter, main_content, foundations, principles, optimization, deployment, trustworthy, futures, labs, arduino, xiao, grove, raspberry, shared, backmatter
🔍 Available keys: frontmatter, volume_1, vol1_foundations, vol1_development, vol1_optimization, vol1_operations, volume_2, vol2_scale, vol2_distributed, vol2_production, vol2_responsible, backmatter, references
💡 Check your .qmd files for \part{key:invalid_key} commands
🛑 Build stopped to prevent incorrect part titles.
```
@@ -107,12 +90,12 @@ When the validation script finds issues:
```
❌ ISSUES FOUND:
📄 book/contents/core/example.qmd:15
📄 quarto/contents/vol1/introduction/introduction.qmd:15
- Key: 'invalid_key' (normalized: 'invalidkey')
- Status: NOT FOUND in part_summaries.yml
- Status: NOT FOUND in summaries.yml
💡 To fix these issues:
1. Add the missing keys to quarto/part_summaries.yml
1. Add the missing keys to quarto/contents/parts/summaries.yml
2. Or correct the key names in the .qmd files
3. Or remove the \part{key:xxx} commands if not needed
```
@@ -126,8 +109,8 @@ Keys are normalized for comparison by:
3. **Removing hyphens** (`-`)
Examples:
- `main_content` → `maincontent`
- `trustworthy` → `trustworthy`
- `vol1_foundations` → `vol1foundations`
- `volume_1` → `volume1`
- `front-matter` → `frontmatter`
## Troubleshooting
@@ -136,13 +119,13 @@ Examples:
1. **Typo in key name**:
```qmd
\part{key:trustworthy} # ✅ Correct
\part{key:trustworthy} # ❌ Typo
\part{key:vol1_foundations} # ✅ Correct
\part{key:vol1_foundationss} # ❌ Typo
```
2. **Missing key in part_summaries.yml**:
2. **Missing key in summaries.yml**:
```yaml
# Add to book/part_summaries.yml
# Add to quarto/contents/parts/summaries.yml
- key: "new_section"
title: "New Section"
description: "Description here"
@@ -150,98 +133,24 @@ Examples:
3. **Incorrect normalization**:
```qmd
\part{key:main_content} # ✅ Will match 'maincontent'
\part{key:main-content} # ✅ Will match 'maincontent'
\part{key:vol1_foundations} # ✅ Will match 'vol1foundations'
\part{key:vol1-foundations} # ✅ Will match 'vol1foundations'
```
### Debugging
1. **Run validation script**:
```bash
python3 scripts/validate_part_keys.py
python3 tools/scripts/utilities/validate_part_keys.py
```
2. **Check specific file**:
```bash
grep -n "\\part{key:" book/contents/**/*.qmd
grep -n "\\part{key:" quarto/contents/**/*.qmd
```
3. **View available keys**:
```bash
python3 -c "
import yaml
with open('quarto/part_summaries.yml') as f:
data = yaml.safe_load(f)
for part in data['parts']:
print(f\"'{part['key']}' -> '{part['title']}'\")
"
```
## Best Practices
1. **Pre-commit hooks catch issues automatically**:
```bash
git add .
git commit -m "Your changes"
# Pre-commit will validate and block if issues found
```
2. **Add new keys to part_summaries.yml first**:
```yaml
- key: "new_section"
title: "New Section"
description: "Description here"
type: "part"
numbered: true
```
3. **Use consistent key naming**:
- Use lowercase with underscores
- Be descriptive but concise
- Follow existing patterns
4. **Test changes**:
```bash
# Test validation manually
pre-commit run validate-part-keys --all-files
# Or test a single file
quarto render quarto/contents/core/example.qmd --to pdf
```
5. **Install pre-commit hooks**:
```bash
pre-commit install
```
## Integration with Git Workflow
The validation is integrated into the pre-commit hooks to catch issues early:
1. **Pre-commit validation** runs before every commit
2. **Fails fast** if any issues are found
3. **Provides detailed error messages** for debugging
4. **Prevents broken commits** from being pushed
This ensures that all commits are consistent and error-free.
### Pre-commit Hook Configuration
The validation is configured in `.pre-commit-config.yaml`:
```yaml
- id: validate-part-keys
name: "Validate part keys in .qmd files"
entry: python scripts/validate_part_keys.py
language: python
additional_dependencies:
- pyyaml
pass_filenames: false
files: ''
```
---
*Last updated: $(date)*
*Validation script: `scripts/validate_part_keys.py`*
*Lua filter: `config/lua/inject-parts.lua`*
*Last updated: January 2026*
*Validation script: `tools/scripts/utilities/validate_part_keys.py`*
*Lua filter: `quarto/filters/inject_parts.lua`*

217
book/docs/PUBLISH_LIVE_WORKFLOW.md
View File

@@ -1,217 +0,0 @@
# 🚀 Publish Live Workflow
## Overview
The publish-live workflow is designed to handle the publication of your Machine Learning Systems textbook with proper PDF management. The key innovation is that **the PDF is available for download but NOT committed to git**.
## 🔄 Workflow Steps
### 1. Manual Trigger
- Go to GitHub Actions → "🚀 Publish Live"
- Fill in the required fields:
- **Description**: What you're publishing
- **Release Type**: patch/minor/major
- **Dev Commit**: Specific commit to publish
- **Confirm**: Type "PUBLISH" to confirm
### 2. Validation & Version Update
- ✅ Validates the dev commit exists and is from dev branch
- ✅ Calculates next version number (based on release type)
- 📝 **Updates version in `quarto/index.qmd`** (automatic)
- ✅ Commits version update to dev branch
- ✅ Merges dev → main branch (includes version update)
- ✅ Creates release tag
- ✅ Pushes to main (triggers production build)
### 3. Production Build
- 🔄 Triggers the "🎮 Controller" workflow
- 📚 Builds HTML and PDF versions
- 📄 Compresses PDF with Ghostscript
- 📦 Uploads build artifacts (including PDF)
### 4. PDF Handling (NEW)
- 📄 Downloads PDF from build artifacts
- 📦 Creates GitHub Release (DRAFT)
- 📄 Uploads PDF to Release Assets
- ✅ PDF is available for download but NOT in git
### 5. Manual Release Notes (NEW)
- 📝 Creates draft release for manual editing
- 🔧 Provides release notes generator script
- ✏️ Allows custom release notes on GitHub website
## 🔢 Version Number Automation
### How It Works
The version number displayed on the website is **automatically updated** during the publish workflow:
1. **Workflow calculates version**: Based on release type (patch/minor/major)
- Patch: v0.4.1 → v0.4.2 (bug fixes)
- Minor: v0.4.1 → v0.5.0 (new features)
- Major: v0.4.1 → v1.0.0 (breaking changes)
2. **Updates `quarto/index.qmd`**:
- Modifies the `doi:` field with the new version
- Commits to dev branch: "chore: update version to vX.X.X"
3. **Merges to main**: Version update included in the merge
4. **Displays on website**:
- Shows as "Version" in the title metadata
- Links to GitHub releases page (via JavaScript)
- Automatically stays in sync with GitHub releases
### Files Involved
- **`quarto/index.qmd`**: Contains the version number (doi field)
- **`quarto/assets/scripts/version-link.js`**: Makes version link to releases page
- **`.github/workflows/publish-live.yml`**: Updates version automatically
### Manual Override
If you need to manually update the version (not recommended):
```yaml
# In quarto/index.qmd
doi: "v0.4.1" # Change this value
```
**Note**: The next publish will overwrite any manual changes.
## 📄 PDF Management Strategy
### What Changed
- **Before**: PDF was committed to git and pushed to gh-pages
- **After**: PDF is uploaded to GitHub Release assets only
### Benefits
- ✅ **No Large Files in Git**: PDF is not tracked in repository
- ✅ **Faster Clones**: Repository stays small
- ✅ **Version Control**: Each release has its own PDF
- ✅ **Download Access**: PDF still available for students
- ✅ **Clean History**: Git history doesn't bloat with PDF changes
### PDF Access Points
1. **Direct Download**: `https://mlsysbook.ai/assets/downloads/Machine-Learning-Systems.pdf`
2. **Release Assets**: `https://github.com/harvard-edge/cs249r_book/releases/download/vX.Y.Z/Machine-Learning-Systems.pdf`
3. **GitHub Pages**: Available in the deployed site
## 🔧 Technical Implementation
### Modified Files
- `.github/workflows/publish-live.yml`: Added PDF download and upload steps
- `.github/workflows/quarto-build-container.yml`: Modified deployment to exclude PDF from git
- `.gitignore`: Added PDF exclusion rules
- `tools/scripts/quarto_publish/publish.sh`: Removed PDF commit
- `binder`: Removed PDF commit
### Key Changes
1. **PDF Download Step**: Downloads PDF from build artifacts
2. **Release Asset Upload**: Uploads PDF to GitHub Release
3. **Git Exclusion**: PDF is copied to assets but not committed
4. **Artifact Management**: PDF is preserved in build artifacts
## 🧪 Testing
Use the test script to verify PDF handling:
```bash
python tools/scripts/test_publish_live.py
```
This will check:
- ✅ PDF exists in assets/
- ✅ PDF is NOT tracked by git
- ✅ PDF is in .gitignore
- ✅ Git status is clean
## 📝 Release Notes Management
The workflow creates **draft releases** on GitHub that you can edit manually. This gives you full control over release notes.
### Writing Release Notes
1. **Run publish-live workflow** → Creates draft release
2. **Edit on GitHub** → Go to the draft release and write your notes
3. **Publish when ready** → Click "Publish release" when satisfied
Release notes should summarize:
- 📖 Content updates and improvements
- 🔧 Technical changes and infrastructure updates
- 🐛 Bug fixes and corrections
## 📋 Usage Instructions
### For Regular Publishing
1. **Develop on dev branch**: Make your changes
2. **Test thoroughly**: Ensure everything works
3. **Trigger publish-live**: Use GitHub Actions UI
4. **Monitor progress**: Watch the workflow run
5. **Verify deployment**: Check the live site
### For Emergency Fixes
1. **Create hotfix branch**: `git checkout -b hotfix/description`
2. **Make minimal changes**: Fix the critical issue
3. **Merge to dev**: `git checkout dev && git merge hotfix/description`
4. **Publish immediately**: Use publish-live workflow
5. **Clean up**: Delete hotfix branch
## 🔍 Troubleshooting
### Common Issues
**PDF Not Found in Artifacts**
- Check that the build completed successfully
- Verify PDF was built in the quarto-build workflow
- Check artifact retention settings
**Release Creation Fails**
- Verify GitHub token permissions
- Check release tag doesn't already exist
- Ensure proper JSON formatting in release notes
**PDF Upload Fails**
- Check file size limits (GitHub has 2GB limit)
- Verify PDF file exists and is valid
- Check network connectivity
### Debug Commands
```bash
# Check PDF status
python tools/scripts/test_publish_live.py
# Check git status
git status
# Check if PDF is tracked
git ls-files assets/downloads/Machine-Learning-Systems.pdf
# Check .gitignore
grep -n "Machine-Learning-Systems.pdf" .gitignore
```
## 📊 Monitoring
### Workflow Status
- **GitHub Actions**: Monitor workflow progress
- **Release Page**: Check release creation
- **Live Site**: Verify deployment
- **PDF Access**: Test download links
### Success Indicators
- ✅ Workflow completes without errors
- ✅ Release is created with PDF asset
- ✅ Live site is updated
- ✅ PDF is accessible for download
- ✅ Git repository remains clean (no PDF commits)
## 🎯 Best Practices
1. **Always test on dev first**: Never publish directly from main
2. **Use descriptive commit messages**: Helps with release notes
3. **Monitor build times**: PDF generation can take 15-30 minutes
4. **Check artifact retention**: Ensure PDFs are preserved
5. **Verify deployment**: Always test the live site after publishing
## 🔗 Related Documentation
- [Development Guide](DEVELOPMENT.md)
- [Build Process](BUILD.md)
- [Container Builds](CONTAINER_BUILDS.md)