lablup / lablup/mlxcel

docs: README claims Homebrew installs on Linux, but the formula is macOS-only

Open Beginner friendly
#1,704 0 comments 0 reactions 0 assignees View on GitHub
priority:medium status:ready type:docs
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.