[PR #1397] [MERGED] MLSys·im 0.1.0 release-prep audit #5172

New Issue

GiteaMirror · 2026-04-19T12:51:23-05:00

GiteaMirror commented

2026-04-19 12:51:23 -05:00

📋 Pull Request Information

Original PR: https://github.com/harvard-edge/cs249r_book/pull/1397
Author: @profvjreddi
Created: 4/18/2026
Status: ✅ Merged
Merged: 4/18/2026
Merged by: @profvjreddi

Base: dev ← Head: review/mlsysim-release-0.1.0

📝 Commits (4)

2051276 docs(mlsysim): release-prep audit fixes for 0.1.0
2c11080 release(mlsysim): add 0.1.0 release notes and runbook
9c0c5b2 mlsysim: nest package layout, enable editable installs, clean lint
172593b fix(mlsysim): repair docs build + lab test after nested-package restructure

📊 Changes

114 files changed (+528 additions, -407 deletions)

View changed files

📝 labs/tests/test_static.py (+1 -1)
📝 mlsysim/CHANGELOG.md (+7 -1)
➕ mlsysim/RELEASE.md (+126 -0)
➕ mlsysim/RELEASE_NOTES_0.1.0.md (+100 -0)
📝 mlsysim/docs/config/_quarto-html.yml (+14 -5)
📝 mlsysim/docs/config/announcement.yml (+1 -1)
📝 mlsysim/docs/contributing.qmd (+5 -6)
📝 mlsysim/docs/for-instructors.qmd (+10 -10)
📝 mlsysim/docs/for-students.qmd (+4 -4)
📝 mlsysim/docs/getting-started.qmd (+8 -8)
📝 mlsysim/docs/index.qmd (+3 -3)
📝 mlsysim/docs/math.qmd (+3 -3)
📝 mlsysim/docs/models-and-solvers.qmd (+1 -1)
📝 mlsysim/docs/references.bib (+8 -0)
📝 mlsysim/docs/tutorials/00_hello_roofline.qmd (+1 -11)
📝 mlsysim/docs/tutorials/01_memory_wall.qmd (+1 -11)
📝 mlsysim/docs/tutorials/02_two_phases.qmd (+1 -11)
📝 mlsysim/docs/tutorials/03_kv_cache.qmd (+1 -11)
📝 mlsysim/docs/tutorials/04_starving_the_gpu.qmd (+2 -12)
📝 mlsysim/docs/tutorials/05_quantization.qmd (+1 -11)

...and 80 more files

📄 Description

Summary

Deep release-prep audit of mlsysim/ ahead of the 0.1.0 cut. Touches docs, build/release artifacts, and a couple of cross-site fixes; no public Python API changes.

Scope was driven by mlsysim/docs/WEBSITE_AUDIT.md plus a fresh sweep of code, tests, wheel build, and broken links.

Changes by phase

Phase 1 — Code & test health (no changes shipped, findings only)

✅ pytest tests/ → 367 passed, 0 failed (CHANGELOG previously underclaimed 334).
✅ Wheel installs cleanly in a fresh venv on Python 3.10–3.14; mlsysim eval Llama3_8B H100 works.
⚠️ pip install -e . fails with the current Hatch sources rewrite. Documented in getting-started.qmd and RELEASE_NOTES_0.1.0.md; recommend non-editable installs until we either flatten the layout or switch backends.
⚠️ Two examples/ files broken end-to-end (filed in the release notes "known issues"):
- 06_multi_objective_pareto.py references a result.pareto_front attribute that doesn't exist on BatchingOptimizerResult.
- gemini_design_loop.py has a multi-line f-string syntax error.
⚠️ ruff check . reports 547 issues in package code, almost entirely F405/F401 from the registry import * pattern. Not release-blocking; can be silenced with a per-rule allowlist in a follow-up.

Phase 2 — Wheel & release artifacts

✅ Version pins consistent across pyproject.toml, CITATION.cff, CHANGELOG.md, __init__.py, README.md BibTeX.
✅ Wheel excludes verified — no tests/, docs/, examples/, notebooks/, paper/, vscode-ext/, Makefile, pytest.ini, generate_appendix.py, or check_*.py ship in mlsysim-0.1.0-py3-none-any.whl.
✅ mlsysim/dist, mlsysim/__pycache__, mlsysim/.pytest_cache already covered by the root .gitignore.
✅ mlsysim/{show,fmt,solvers}.py confirmed as intentional public API modules (re-exports + display helpers); labs/ is the importable mlsysim.labs UI toolkit, not the marimo apps.

Phase 3 — Docs site audit

Hero "See it in action" code on docs/index.qmd and "Your First Analysis" on getting-started.qmd updated to the actual Engine.solve(ResNet50, A100, bs=1, fp16) output: Memory / 0.54 ms / 1843.
Standardized the typographic brand to MLSys·im in the navbar title, OG/Twitter metadata, sub-navbar, and the shared cross-site dropdown (shared/config/navbar-common.yml). Body-text references to MLSYSIM / MLSysim are intentionally left alone — they read as the all-caps brand and the academic citation respectively.
Reconciled the quartodoc list against mlsysim.core.solver: added the 4 missing classes (BatchingOptimizer, ForwardModel, NetworkRooflineModel, PlacementOptimizer).
Added the 3 orphan tutorials (01_pipeline_callbacks, 02_differential_explainer, 12_design_space_exploration) to the sidebar. Removed a duplicate "Differential Explainer" card on tutorials/index.qmd.
Fixed every Unable to resolve link target warning Quarto emitted:
- tutorials/hello_world.qmd → tutorials/00_hello_roofline.qmd
- tutorials/llm_serving.qmd → tutorials/02_two_phases.qmd
- tutorials/sustainability.qmd → tutorials/07_geography.qmd
- tutorials/distributed.qmd (in for-instructors.qmd) → tutorials/06_scaling_1000_gpus.qmd
- tutorials/11_full_stack_audit.qmd → tutorials/12_full_stack_audit.qmd (4 tutorial files + TEMPLATE.md)
- api/core.formulas.qmd (3 refs in math.qmd) → GitHub source link
- api/core.dse.qmd (in models-and-solvers.qmd) → GitHub source link
- Added missing @mlsysbook2024 BibTeX entry referenced from whitepaper.qmd.
Fixed the announcement-banner Get started → link (config/announcement.yml) — it was a relative path that broke on every sub-page; now an absolute URL.
Softened the Colab/Binder language until launch buttons are wired in.
Bumped the documented Python requirement from 3.9+ to 3.10+ (matches pyproject.toml).

Phase 4 — Cross-site & ecosystem integration

Fixed the CLI sample on site/index.qmd's mlsysim card: llama-3-70b --batch 1 was wrong on both the model name (no such alias) and the flag (--batch-size). Now reads Llama3_70B H100 --batch-size 1.
Verified shared/config/navbar-common.yml "Build" dropdown points at https://mlsysbook.ai/mlsysim/ and uses the same MLSys·im text as the in-site nav.
Verified the publish workflow (mlsysim-publish-live.yml) is workflow_dispatch only and that vars.MLSYSIM_DOCS / vars.DEV_MLSYSIM_PATH are referenced (env vars must be set in repo settings — documented in RELEASE.md).

Phase 5 — Repo hygiene

Confirmed mlsysim/dist, mlsysim/__pycache__, mlsysim/.pytest_cache are gitignored on dev (no untracked-but-ignored cruft).
Reviewed mlsysim/{show,fmt,solvers}.py, vscode-ext/, labs/, and generate_appendix.py — all keep/exclude decisions match what the wheel actually ships.

Phase 6 — Release deliverables

New mlsysim/RELEASE.md — copy-pasteable runbook for tag → build → PyPI → docs deploy → GitHub release → post-release verification.
New mlsysim/RELEASE_NOTES_0.1.0.md — install/quickstart, highlights, and a frank "known limitations & gotchas" section flagging the editable-install bug, the two broken examples, the missing slides-latest GitHub release, and the not-yet-wired Colab/Binder buttons.
Updated mlsysim/CHANGELOG.md test count 334 → 367 (actual).

Release gates

Gate	Status
`pytest tests/` (367 tests)	✅ pass
Wheel build (`make build`)	✅ produces `dist/mlsysim-0.1.0-py3-none-any.whl` + `.tar.gz`
Wheel install in clean venv	✅ `import mlsysim` + CLI works
Wheel excludes verified	✅ no tests/docs/examples/paper/etc.
Version pins aligned (5 files)	✅ all `0.1.0` / `2026-04-01`
Docs build (`quarto render`)	✅ no `Unable to resolve link target` warnings
CLI smoke (`mlsysim eval`, `zoo`, `schema`)	✅ matches docs
`editable install` (`pip install -e .`)	⚠️ documented limitation, not a release blocker
`ruff` clean	⚠️ 547 issues, almost all from registry `import *`; not release-blocking

Out of scope (deliberately deferred)

Adding new solvers or changing the public Python API.
Fixing examples/06_multi_objective_pareto.py and examples/gemini_design_loop.py (filed in release notes, low priority — both excluded from wheel).
Wiring marimo export into the validate workflow / publishing the slide-deck slides-latest tag (out-of-repo prerequisites).
Body-text rebranding of MLSYSIM → MLSys·im across the docs corpus (intentional left alone — reads as all-caps brand voice).
Migrating off the Hatch sources rewrite to enable editable installs (will likely require flattening the package layout).

Test plan

CI: mlsysim-validate-dev passes on this PR.
Manual: cd mlsysim && pytest tests/ -q reports 367 passed.
Manual: cd mlsysim/docs && quarto render produces no Unable to resolve link target warnings.
Manual: pip install mlsysim/dist/mlsysim-0.1.0-py3-none-any.whl in a fresh venv, then mlsysim eval Llama3_8B H100 --batch-size 32 returns a scorecard.
Manual: open the rendered docs site (mlsysim/docs/_build/index.html) and verify the hero example output, navbar branding, and announcement banner link.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/harvard-edge/cs249r_book/pull/1397 **Author:** [@profvjreddi](https://github.com/profvjreddi) **Created:** 4/18/2026 **Status:** ✅ Merged **Merged:** 4/18/2026 **Merged by:** [@profvjreddi](https://github.com/profvjreddi) **Base:** `dev` ← **Head:** `review/mlsysim-release-0.1.0` --- ### 📝 Commits (4) - [`2051276`](https://github.com/harvard-edge/cs249r_book/commit/20512761c986cc6a529cb0b49b23c9de059261d2) docs(mlsysim): release-prep audit fixes for 0.1.0 - [`2c11080`](https://github.com/harvard-edge/cs249r_book/commit/2c110808d7131082ef48d7bd8dde56f9c9d2a8a2) release(mlsysim): add 0.1.0 release notes and runbook - [`9c0c5b2`](https://github.com/harvard-edge/cs249r_book/commit/9c0c5b2c792e66b67a0b58e5383f4a38472f574c) mlsysim: nest package layout, enable editable installs, clean lint - [`172593b`](https://github.com/harvard-edge/cs249r_book/commit/172593bf4472e43639d30f6716ac0bd955135c06) fix(mlsysim): repair docs build + lab test after nested-package restructure ### 📊 Changes **114 files changed** (+528 additions, -407 deletions) <details> <summary>View changed files</summary> 📝 `labs/tests/test_static.py` (+1 -1) 📝 `mlsysim/CHANGELOG.md` (+7 -1) ➕ `mlsysim/RELEASE.md` (+126 -0) ➕ `mlsysim/RELEASE_NOTES_0.1.0.md` (+100 -0) 📝 `mlsysim/docs/config/_quarto-html.yml` (+14 -5) 📝 `mlsysim/docs/config/announcement.yml` (+1 -1) 📝 `mlsysim/docs/contributing.qmd` (+5 -6) 📝 `mlsysim/docs/for-instructors.qmd` (+10 -10) 📝 `mlsysim/docs/for-students.qmd` (+4 -4) 📝 `mlsysim/docs/getting-started.qmd` (+8 -8) 📝 `mlsysim/docs/index.qmd` (+3 -3) 📝 `mlsysim/docs/math.qmd` (+3 -3) 📝 `mlsysim/docs/models-and-solvers.qmd` (+1 -1) 📝 `mlsysim/docs/references.bib` (+8 -0) 📝 `mlsysim/docs/tutorials/00_hello_roofline.qmd` (+1 -11) 📝 `mlsysim/docs/tutorials/01_memory_wall.qmd` (+1 -11) 📝 `mlsysim/docs/tutorials/02_two_phases.qmd` (+1 -11) 📝 `mlsysim/docs/tutorials/03_kv_cache.qmd` (+1 -11) 📝 `mlsysim/docs/tutorials/04_starving_the_gpu.qmd` (+2 -12) 📝 `mlsysim/docs/tutorials/05_quantization.qmd` (+1 -11) _...and 80 more files_ </details> ### 📄 Description ## Summary Deep release-prep audit of `mlsysim/` ahead of the 0.1.0 cut. Touches docs, build/release artifacts, and a couple of cross-site fixes; **no public Python API changes**. Scope was driven by `mlsysim/docs/WEBSITE_AUDIT.md` plus a fresh sweep of code, tests, wheel build, and broken links. ## Changes by phase ### Phase 1 — Code & test health (no changes shipped, findings only) - ✅ `pytest tests/` → **367 passed, 0 failed** (CHANGELOG previously underclaimed 334). - ✅ Wheel installs cleanly in a fresh venv on Python 3.10–3.14; `mlsysim eval Llama3_8B H100` works. - ⚠️ `pip install -e .` fails with the current Hatch `sources` rewrite. Documented in `getting-started.qmd` and `RELEASE_NOTES_0.1.0.md`; recommend non-editable installs until we either flatten the layout or switch backends. - ⚠️ Two `examples/` files broken end-to-end (filed in the release notes "known issues"): - `06_multi_objective_pareto.py` references a `result.pareto_front` attribute that doesn't exist on `BatchingOptimizerResult`. - `gemini_design_loop.py` has a multi-line f-string syntax error. - ⚠️ `ruff check .` reports 547 issues in package code, almost entirely `F405`/`F401` from the registry `import *` pattern. Not release-blocking; can be silenced with a per-rule allowlist in a follow-up. ### Phase 2 — Wheel & release artifacts - ✅ Version pins consistent across `pyproject.toml`, `CITATION.cff`, `CHANGELOG.md`, `__init__.py`, `README.md` BibTeX. - ✅ Wheel excludes verified — no `tests/`, `docs/`, `examples/`, `notebooks/`, `paper/`, `vscode-ext/`, `Makefile`, `pytest.ini`, `generate_appendix.py`, or `check_*.py` ship in `mlsysim-0.1.0-py3-none-any.whl`. - ✅ `mlsysim/dist`, `mlsysim/__pycache__`, `mlsysim/.pytest_cache` already covered by the root `.gitignore`. - ✅ `mlsysim/{show,fmt,solvers}.py` confirmed as intentional public API modules (re-exports + display helpers); `labs/` is the importable `mlsysim.labs` UI toolkit, not the marimo apps. ### Phase 3 — Docs site audit - Hero "See it in action" code on `docs/index.qmd` and "Your First Analysis" on `getting-started.qmd` updated to the actual `Engine.solve(ResNet50, A100, bs=1, fp16)` output: `Memory / 0.54 ms / 1843`. - Standardized the typographic brand to **`MLSys·im`** in the navbar title, OG/Twitter metadata, sub-navbar, and the shared cross-site dropdown (`shared/config/navbar-common.yml`). Body-text references to `MLSYSIM` / `MLSysim` are intentionally left alone — they read as the all-caps brand and the academic citation respectively. - Reconciled the quartodoc list against `mlsysim.core.solver`: added the 4 missing classes (`BatchingOptimizer`, `ForwardModel`, `NetworkRooflineModel`, `PlacementOptimizer`). - Added the 3 orphan tutorials (`01_pipeline_callbacks`, `02_differential_explainer`, `12_design_space_exploration`) to the sidebar. Removed a duplicate "Differential Explainer" card on `tutorials/index.qmd`. - Fixed every `Unable to resolve link target` warning Quarto emitted: - `tutorials/hello_world.qmd` → `tutorials/00_hello_roofline.qmd` - `tutorials/llm_serving.qmd` → `tutorials/02_two_phases.qmd` - `tutorials/sustainability.qmd` → `tutorials/07_geography.qmd` - `tutorials/distributed.qmd` (in `for-instructors.qmd`) → `tutorials/06_scaling_1000_gpus.qmd` - `tutorials/11_full_stack_audit.qmd` → `tutorials/12_full_stack_audit.qmd` (4 tutorial files + `TEMPLATE.md`) - `api/core.formulas.qmd` (3 refs in `math.qmd`) → GitHub source link - `api/core.dse.qmd` (in `models-and-solvers.qmd`) → GitHub source link - Added missing `@mlsysbook2024` BibTeX entry referenced from `whitepaper.qmd`. - Fixed the announcement-banner `Get started →` link (`config/announcement.yml`) — it was a relative path that broke on every sub-page; now an absolute URL. - Softened the Colab/Binder language until launch buttons are wired in. - Bumped the documented Python requirement from 3.9+ to 3.10+ (matches `pyproject.toml`). ### Phase 4 — Cross-site & ecosystem integration - Fixed the CLI sample on `site/index.qmd`'s mlsysim card: `llama-3-70b --batch 1` was wrong on both the model name (no such alias) and the flag (`--batch-size`). Now reads `Llama3_70B H100 --batch-size 1`. - Verified `shared/config/navbar-common.yml` "Build" dropdown points at `https://mlsysbook.ai/mlsysim/` and uses the same `MLSys·im` text as the in-site nav. - Verified the publish workflow (`mlsysim-publish-live.yml`) is `workflow_dispatch` only and that `vars.MLSYSIM_DOCS` / `vars.DEV_MLSYSIM_PATH` are referenced (env vars must be set in repo settings — documented in `RELEASE.md`). ### Phase 5 — Repo hygiene - Confirmed `mlsysim/dist`, `mlsysim/__pycache__`, `mlsysim/.pytest_cache` are gitignored on `dev` (no untracked-but-ignored cruft). - Reviewed `mlsysim/{show,fmt,solvers}.py`, `vscode-ext/`, `labs/`, and `generate_appendix.py` — all keep/exclude decisions match what the wheel actually ships. ### Phase 6 — Release deliverables - New `mlsysim/RELEASE.md` — copy-pasteable runbook for tag → build → PyPI → docs deploy → GitHub release → post-release verification. - New `mlsysim/RELEASE_NOTES_0.1.0.md` — install/quickstart, highlights, and a frank "known limitations & gotchas" section flagging the editable-install bug, the two broken examples, the missing `slides-latest` GitHub release, and the not-yet-wired Colab/Binder buttons. - Updated `mlsysim/CHANGELOG.md` test count 334 → 367 (actual). ## Release gates | Gate | Status | |---|---| | `pytest tests/` (367 tests) | ✅ pass | | Wheel build (`make build`) | ✅ produces `dist/mlsysim-0.1.0-py3-none-any.whl` + `.tar.gz` | | Wheel install in clean venv | ✅ `import mlsysim` + CLI works | | Wheel excludes verified | ✅ no tests/docs/examples/paper/etc. | | Version pins aligned (5 files) | ✅ all `0.1.0` / `2026-04-01` | | Docs build (`quarto render`) | ✅ no `Unable to resolve link target` warnings | | CLI smoke (`mlsysim eval`, `zoo`, `schema`) | ✅ matches docs | | `editable install` (`pip install -e .`) | ⚠️ documented limitation, not a release blocker | | `ruff` clean | ⚠️ 547 issues, almost all from registry `import *`; not release-blocking | ## Out of scope (deliberately deferred) - Adding new solvers or changing the public Python API. - Fixing `examples/06_multi_objective_pareto.py` and `examples/gemini_design_loop.py` (filed in release notes, low priority — both excluded from wheel). - Wiring `marimo export` into the validate workflow / publishing the slide-deck `slides-latest` tag (out-of-repo prerequisites). - Body-text rebranding of `MLSYSIM` → `MLSys·im` across the docs corpus (intentional left alone — reads as all-caps brand voice). - Migrating off the Hatch `sources` rewrite to enable editable installs (will likely require flattening the package layout). ## Test plan - [ ] CI: `mlsysim-validate-dev` passes on this PR. - [ ] Manual: `cd mlsysim && pytest tests/ -q` reports 367 passed. - [ ] Manual: `cd mlsysim/docs && quarto render` produces no `Unable to resolve link target` warnings. - [ ] Manual: `pip install mlsysim/dist/mlsysim-0.1.0-py3-none-any.whl` in a fresh venv, then `mlsysim eval Llama3_8B H100 --batch-size 32` returns a scorecard. - [ ] Manual: open the rendered docs site (`mlsysim/docs/_build/index.html`) and verify the hero example output, navbar branding, and announcement banner link. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-04-19 12:51:23 -05:00

GiteaMirror closed this issue

2026-04-19 12:51:23 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/cs249r_book#5172