Skip to content

docs: revert getting-started.md tutorial to xgb_train (pytorch_train crashes on Apple Silicon) - #1871

Open
sallycr wants to merge 1 commit into
mainfrom
sallycr/revert-pytorch-train-tutorial-mps
Open

docs: revert getting-started.md tutorial to xgb_train (pytorch_train crashes on Apple Silicon)#1871
sallycr wants to merge 1 commit into
mainfrom
sallycr/revert-pytorch-train-tutorial-mps

Conversation

@sallycr

@sallycr sallycr commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator

What type of PR is this? (check all applicable)

  • Refactor
  • Feature
  • Bug Fix
  • Optimization
  • Documentation Update

What changed?

Reverts docs/user-guides/getting-started/getting-started.md's tutorial to its pre-#1749 state, teaching the in-core XGBoost pipeline (python/examples/pipelines/california_housing_xgb/) again instead of michelangelo-examples' pytorch_train (PyTorch Lightning). No other file from #1749 is touched — docs/getting-started/sandbox-setup.md, docs/user-guides/examples/index.md, and docs/user-guides/ml-pipelines/workflow-patterns.md's repoints to michelangelo-examples are unaffected and still correct.

Why?

#1749 switched the tutorial's flagship worked example to pytorch_train. Its documented local-run command (python -m michelangelo_examples.california_housing.pipelines.pytorch_train.pipeline) crashes on any Apple Silicon Mac:

ValueError: You set `strategy=<...RayDDPStrategy...>` but strategies from the DDP
family are not supported on the MPS accelerator. Either explicitly set
`accelerator='cpu'` or change the strategy.

Root-caused and tracked as issue #1867, with a design already written up (fix requires adding a new accelerator field to core michelangelo's LightningTrainerKwargs — not something fixable from docs or from michelangelo-examples alone, since that dataclass has no such field today). Also confirmed RayDeepSpeedStrategy doesn't sidestep this — it's a subclass of Lightning's own DDPStrategy/ParallelStrategy, so it hits the identical MPS rejection.

Until #1867's fix ships, pytorch_train's local-run path is broken for a likely-large fraction of individual contributors' dev machines (any Apple Silicon Mac). The in-core XGBoost example has no PyTorch/MPS dependency at all and runs clean end-to-end (re-verified locally, no manual workarounds). Reverting the tutorial back to it keeps getting-started.md trustworthy in the meantime; the switch to pytorch_train can be reinstated once #1867 is fixed and released.

How did you test it?

Potential risks

None beyond a temporary doc/tutorial content change. No code changes.

Breaking Changes

  • No breaking changes
  • API changes (Go exported symbols or function signatures, Python public functions or classes)
  • Proto changes (enum value renumbering, field number changes, field removal, service removal)
  • Helm changes (new required values, renamed or removed keys, changed value semantics)
  • Config/deployment changes (new required env vars, renamed container args, changed ports or mount paths)

Release notes

N/A

Documentation Changes

Yes — reverts the getting-started tutorial's flagship example from pytorch_train back to the in-core XGBoost pipeline, until #1867 (pytorch_train crashes on Apple Silicon) is fixed.

…crashes on Apple Silicon

PR #1749 switched the tutorial's flagship worked example from the in-core XGBoost pipeline to michelangelo-examples' pytorch_train (PyTorch Lightning). pytorch_train's documented local-run command crashes on any Apple Silicon Mac with a DDP+MPS incompatibility (see spec 036 / issue #1867) -- not something a doc fix can work around, since the fix has to add a new accelerator field to core michelangelo's LightningTrainerKwargs dataclass first. Reverting the tutorial to the XGBoost example (which has no PyTorch/MPS dependency at all, confirmed clean end-to-end) until that fix ships.
@github-actions github-actions Bot added the docs label Aug 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants