Skip to content

chore: purge leaked mlxcel-internal issue/PR numbers from public source and docs #40

@inureyes

Description

@inureyes

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:

  1. 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).
  2. 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.
  3. 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

  1. Enumerate the distinct bare #NNN references and classify each as internal / upstream / false-positive.
  2. 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.
  3. For upstream: keep and qualify with org/repo#NNN so the reference is unambiguous.
  4. Split into reviewable batches (e.g. src/ vs docs/ vs tests/).

Acceptance criteria

  • All bare references to mlxcel-internal issues/PRs are removed or rephrased; none remain in src/, tests/, docs/, examples/, CHANGELOG.md, debian/changelog.
  • Legitimate upstream references are preserved (and ideally qualified as org/repo#NNN).
  • A regression guard is added or documented — e.g. a pre-commit/CI grep flagging new bare 3+digit # references on changed lines (with an allowlist for qualified upstream refs), or document the pre-flight check git 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/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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsUser and developer documentationpriority:mediumMedium prioritystatus:readyReady to be worked ontype:choreMaintenance tasks (build, CI, etc.)

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions