docs: README claims Homebrew installs on Linux, but the formula is macOS-only
- Dominant language
- Rust
- Stars
- 467
- Forks
- 54
- Avg merge
- 4h 25m
- Merged PRs (30d)
- 310
Description
## Summary
The README advertises the Homebrew formula for macOS and Linux, but the release automation ships exactly one artifact by design: macOS Apple Silicon. A Linux user following the quick start gets nothing installable.
## Background
The Homebrew bump workflow is deliberately single-artifact; the Linux CUDA variants are hardware-specific and distributed only as raw GitHub Release assets. The README sentence promises a Linux path that does not exist.
## Proposed Solution
Correct the README sentence to macOS Apple Silicon and point Linux users at the GitHub Release assets. Optionally add a short "Install a release" section to `docs/installation.md`.
## Implementation Notes
- `README.md:45` (confirmed): "The Homebrew formula installs the latest released `mlxcel` and `mlxcel-server` binaries on macOS and Linux".
- `.github/workflows/update_homebrew_formula.yml:3-6` (confirmed): "mlxcel ships a single brew-supported artifact (macOS Apple Silicon); the Linux CUDA variants are hardware-specific and continue to be distributed only as raw GitHub Release assets."
- `.github/workflows/update_homebrew_formula.yml:72` (confirmed): the bump fetches only `mlxcel-macos-aarch64.zip`; the guard aborts unless the formula has exactly one version/url/sha256 stanza.
- Secondary gap: `docs/installation.md` never mentions Homebrew or any prebuilt-release path (its only `brew` is `brew install ffmpeg`); it jumps to `git clone` + `cargo build`.
## Acceptance Criteria
- [ ] README no longer claims brew support on Linux.
- [ ] Linux users are pointed at the raw release assets.
---
## Original Suggestion
### Title: docs: README claims Homebrew installs on Linux, but the formula is macOS-only
The README advertises the Homebrew formula for macOS **and Linux**, but the formula ships exactly one artifact — macOS Apple Silicon — by the release automation's own design. A Linux user following the quick start gets nothing installable.
## Evidence
- `README.md:45` — "The Homebrew formula installs the latest released `mlxcel` and `mlxcel-server` binaries on macOS and Linux"
- `.github/workflows/update_homebrew_formula.yml:3-6` — "mlxcel ships a single brew-supported artifact (macOS Apple Silicon); the Linux CUDA variants are hardware-specific and continue to be distributed only as raw GitHub Release assets."
- `.github/workflows/update_homebrew_formula.yml:72` — the bump fetches only `mlxcel-macos-aarch64.zip`; the guard at `:107-115` aborts unless the formula has exactly one version/url/sha256 stanza
Secondary gap: `docs/installation.md` never mentions Homebrew or any prebuilt-release path (its only `brew` is `brew install ffmpeg` at `:84`); it jumps straight to `git clone` + `cargo build` at `:93-95`.
## Suggested fix
Correct the README sentence to macOS Apple Silicon (pointing Linux users at the GitHub Release assets), and optionally add a short "Install a release" section to `docs/installation.md`. Ground truth is fully written in the workflow comment.
## Acceptance criteria
- [ ] README no longer claims brew support on Linux
- [ ] Linux users are pointed at the raw release assets
Contributor guide
Research direction
Start at README.md:45 and read .github/workflows/update_homebrew_formula.yml:3-6 and :72 to confirm the supported artifact and release distribution. Update the README to describe macOS Apple Silicon Homebrew support and point Linux users to GitHub Release assets; add the optional release-installation guidance in docs/installation.md if included. Done means the README no longer promises Linux Homebrew support and Linux users have a documented release path.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github, github-actions
- Domain
- documentation, release
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100