Problem
The public repository carries many bare #NNN references that point to mlxcel-internal issues and PRs, not to anything in lablup/mlxcel. These leaked in through the historical internal→public port workflow, which until 2026-05-20 deliberately kept internal issue numbers verbatim in code comments. That convention has since been reversed: internal issue/PR numbers must never appear anywhere in the public repo (code comments, docs, commit subjects, PR bodies). New ports now map an internal reference to its public-equivalent number when one demonstrably exists, or describe the change without a number. This issue tracks cleaning up the pre-existing leaked references.
Why it matters
A public reader who follows e.g. #603 lands on an unrelated lablup/mlxcel issue or a 404 — the number is only meaningful in the private internal repo. It also exposes internal planning/numbering publicly and is inconsistent with the current contribution policy.
Scope (measured, with caveats)
A heuristic scan (git grep -lE "#[0-9]{3,}") matches ~300 tracked files and ~435 distinct 3+digit numbers, concentrated in src/ (259 files) and tests/ (26), with a handful in docs/, examples/, CHANGELOG.md, and debian/changelog. The raw count over-counts — this is a triage task, not a blind strip. Three classes:
- Internal leaks (remove or map): bare references to mlxcel-internal issues/PRs, e.g.
src/audio/nemotron_h_nano_omni/config.rs:15 (issue #582), the (PR #721/#724/#727) annotations in docs/benchmark_results/model_tests_m1ultra.md, and #719 on the qwen3-vl rows of docs/benchmark_results/model_tests_m5max.md. Mostly in the #100–#999 range (~416 distinct numbers).
- Legitimate upstream references (keep, ideally qualify): references to
ml-explore/mlx-lm, Blaizzy/mlx-vlm, HuggingFace transformers, etc. — e.g. docs/benchmark_results/model_tests_m1ultra.md:14 cites mlx-lm #1240 and :15 cites mlx-vlm #1181 as baseline-checkout PR titles. These should stay, but read more clearly when qualified as ml-explore/mlx-lm#1240.
- False positives (ignore): URL fragments and corpus fixtures, e.g.
tests/fixtures/wikitext2_excerpt.txt and a ...html#1202 anchor in the webpage asset.
Proposed approach
- Enumerate the distinct bare
#NNN references and classify each as internal / upstream / false-positive.
- For internal: map to the public-equivalent PR/issue number where one demonstrably exists (verify same subject + mechanism — as was done for internal
#734 → public #34); otherwise rephrase the comment/doc to describe the symptom without a number.
- For upstream: keep and qualify with
org/repo#NNN so the reference is unambiguous.
- Split into reviewable batches (e.g.
src/ vs docs/ vs tests/).
Acceptance criteria
Notes
This is tech debt accumulated from prior ports, not introduced by any single change. Detection heuristic: public lablup/mlxcel PRs are 1–2 digits, so any bare 3+digit # on a changed line is almost certainly a leak or an unqualified upstream reference.
Problem
The public repository carries many bare
#NNNreferences that point to mlxcel-internal issues and PRs, not to anything inlablup/mlxcel. These leaked in through the historical internal→public port workflow, which until 2026-05-20 deliberately kept internal issue numbers verbatim in code comments. That convention has since been reversed: internal issue/PR numbers must never appear anywhere in the public repo (code comments, docs, commit subjects, PR bodies). New ports now map an internal reference to its public-equivalent number when one demonstrably exists, or describe the change without a number. This issue tracks cleaning up the pre-existing leaked references.Why it matters
A public reader who follows e.g.
#603lands on an unrelatedlablup/mlxcelissue or a 404 — the number is only meaningful in the private internal repo. It also exposes internal planning/numbering publicly and is inconsistent with the current contribution policy.Scope (measured, with caveats)
A heuristic scan (
git grep -lE "#[0-9]{3,}") matches ~300 tracked files and ~435 distinct 3+digit numbers, concentrated insrc/(259 files) andtests/(26), with a handful indocs/,examples/,CHANGELOG.md, anddebian/changelog. The raw count over-counts — this is a triage task, not a blind strip. Three classes:src/audio/nemotron_h_nano_omni/config.rs:15(issue #582), the(PR #721/#724/#727)annotations indocs/benchmark_results/model_tests_m1ultra.md, and#719on the qwen3-vl rows ofdocs/benchmark_results/model_tests_m5max.md. Mostly in the#100–#999range (~416 distinct numbers).ml-explore/mlx-lm,Blaizzy/mlx-vlm, HuggingFacetransformers, etc. — e.g.docs/benchmark_results/model_tests_m1ultra.md:14cites mlx-lm#1240and:15cites mlx-vlm#1181as baseline-checkout PR titles. These should stay, but read more clearly when qualified asml-explore/mlx-lm#1240.tests/fixtures/wikitext2_excerpt.txtand a...html#1202anchor in the webpage asset.Proposed approach
#NNNreferences and classify each as internal / upstream / false-positive.#734→ public#34); otherwise rephrase the comment/doc to describe the symptom without a number.org/repo#NNNso the reference is unambiguous.src/vsdocs/vstests/).Acceptance criteria
src/,tests/,docs/,examples/,CHANGELOG.md,debian/changelog.org/repo#NNN).#references on changed lines (with an allowlist for qualified upstream refs), or document the pre-flight checkgit diff | grep -nE "#[0-9]{3,}"in CONTRIBUTING/AGENTS.Notes
This is tech debt accumulated from prior ports, not introduced by any single change. Detection heuristic: public
lablup/mlxcelPRs are 1–2 digits, so any bare 3+digit#on a changed line is almost certainly a leak or an unqualified upstream reference.