From 04dba44eb235d85808c132600153bdc9c5f3e7a5 Mon Sep 17 00:00:00 2001 From: Alexander Dobin Date: Tue, 18 Aug 2026 22:43:10 -0700 Subject: [PATCH] docs: make issue and PR references readable instead of dead links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Issue and PR references in this repository identify entries in trackers that are not public. Nine of them were written as ordinary markdown links, so they looked like destinations and resolved to 404 when followed, and nothing anywhere said what the remaining nineteen bare `gpudge_arc#N` / `shardad #N` tokens were. ### What changes - **The dead links become plain provenance tokens.** `[#66](…)` is now `` `gpudge_arc#66` ``: the reference is kept, the invitation to click a page that does not exist is not. Seven links across `CHANGELOG.md` and the 2026-06-27 review report. - **A visible note now says what the tokens are**, in the three places a reader meets them without necessarily passing the others: the top of `CHANGELOG.md`, the `## Resolution status` section of the 2026-06-27 report, and above the table in `docs/reviews/README.md`. Until now the only explanation was inside an HTML comment at the foot of the changelog, which renders to nobody. `shardad`'s two links are deliberately left as links: the README explains in the same breath that the repository is not public, and the link becomes correct rather than dead if that changes. ### Verification - No unexplained internal reference across all 78 files, and **zero** `github.com/ArcInstitute/gpudge_arc` URLs remain (was 7). - This tree, no GPU: **626 passed / 202 skipped** (828 collected). CI-equivalent, with `shardad` unimportable: **556 / 134**. `ruff check src/ tests/ examples/` clean. - `benchmarks/rapids_sc/`, which lives only here, is byte-identical across the update — sha256 manifest before and after, 10 files, no diff. - A regeneration from the same source `diff -rq`s clean against this branch. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 15 ++++++++++----- docs/reviews/2026-06-27-gpudge-ultrareview.md | 11 ++++++++--- docs/reviews/README.md | 4 ++++ 3 files changed, 22 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1681e5e..150332d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to gpudge are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +> **A note on issue and PR numbers.** References such as `#124`, `gpudge_arc#115` +> and `shardad #246` throughout this file are **provenance, not links**: they +> identify entries in issue trackers that are not public, and will not resolve +> from here. They are kept so that each change can be traced back to the +> discussion that produced it. + ## [Unreleased] ## [0.8.0] — 2026-08-18 @@ -77,7 +83,7 @@ H100, and 3 were refuted and are not listed here). coercion.** Assigning to a view's `.X` writes through to the parent instead of rebinding, so the coercion vanished while its warning claimed success — dropping every gather tile onto scipy slicing, the regression - [#66](https://github.com/ArcInstitute/gpudge_arc/issues/66) added it to + `gpudge_arc#66` added it to prevent. On an already-CSR view the assignment also ran a full O(n_obs × n_var) sparse scatter into the caller's matrix. The coerced matrix is now bound to a local **for views only**. A materialized `AnnData` is still @@ -264,7 +270,7 @@ it go red. ### Added - **`de(cell_source=…)` — a public bring-your-own cell source** - ([#86](https://github.com/ArcInstitute/gpudge_arc/issues/86)). A third input + (`gpudge_arc#86`). A third input mode, alongside `adata=` and `archive=`, taking a callable that yields one public `CellGroup(label, X, rows=None)` per target group plus `targets=` / `var_names=`. It runs the same `refpool_de_core` as the other @@ -323,7 +329,7 @@ it go red. `tau_star` and `tau_star_se`. - **`de(archive=…)` reads `layout='cell'` shardad archives** - ([#110](https://github.com/ArcInstitute/gpudge_arc/issues/110)): streaming DE + (`gpudge_arc#110`): streaming DE now works on `.csad` per-cell archives, the form several VCI production datasets are written in, removing the need for a shard-layout twin of a 40+ GB archive. `de(shard_archive=…)` is the deprecated spelling of the new @@ -1038,8 +1044,7 @@ ULP of the CPU baseline on every assertable column. + tagged here, so they carry no compare link. --> [Unreleased]: https://github.com/ArcInstitute/gpudge/compare/v0.8.0...HEAD [0.8.0]: https://github.com/ArcInstitute/gpudge/compare/v0.7.0...v0.8.0 diff --git a/docs/reviews/2026-06-27-gpudge-ultrareview.md b/docs/reviews/2026-06-27-gpudge-ultrareview.md index d56e53a..19871b8 100644 --- a/docs/reviews/2026-06-27-gpudge-ultrareview.md +++ b/docs/reviews/2026-06-27-gpudge-ultrareview.md @@ -28,11 +28,16 @@ No live correctness bug exists in any realistic, supported code path. The core M ## Resolution status -Added 2026-08-18. **All 22 findings were addressed in v0.3.1 ([#59](https://github.com/ArcInstitute/gpudge_arc/pull/59))**, the release immediately following this review; two of them deliberately by deciding no code should change. Statuses below were re-verified against the tree at `v0.8.0`, and the *Evidence* column names something you can open — a regression test that cites the finding ID, or the code that now carries the guard. +> `gpudge_arc#59` and similar tokens below are **provenance, not links**: they +> identify entries in an issue tracker that is not public and will not resolve +> from here. They are kept so each disposition can be traced to the change that +> made it. + +Added 2026-08-18. **All 22 findings were addressed in v0.3.1 (`gpudge_arc#59`)**, the release immediately following this review; two of them deliberately by deciding no code should change. Statuses below were re-verified against the tree at `v0.8.0`, and the *Evidence* column names something you can open — a regression test that cites the finding ID, or the code that now carries the guard. | # | Severity | Finding | Status | Evidence | |---|---|---|---|---| -| H1 | High | NaN/None `groupby` labels bucketed into `'nan'`/`'None'` groups | **Fixed** (v0.3.1); guard broadened in v0.8.0 ([#124](https://github.com/ArcInstitute/gpudge_arc/pull/124)) | `_ingest.MISSING_LABEL_SPELLINGS` and the mirroring guard in `_shard_stream.py`, which was the only streaming layout when this was fixed; `_cell_stream.py` gained the same screen when the cell layout arrived in v0.7.0. ⚠️ One backend-parity gap remains open as [#127](https://github.com/ArcInstitute/gpudge_arc/issues/127) — a group *genuinely* named `nan` is rejected on streaming but accepted in memory | +| H1 | High | NaN/None `groupby` labels bucketed into `'nan'`/`'None'` groups | **Fixed** (v0.3.1); guard broadened in v0.8.0 (`gpudge_arc#124`) | `_ingest.MISSING_LABEL_SPELLINGS` and the mirroring guard in `_shard_stream.py`, which was the only streaming layout when this was fixed; `_cell_stream.py` gained the same screen when the cell layout arrived in v0.7.0. ⚠️ One backend-parity gap remains open as `gpudge_arc#127` — a group *genuinely* named `nan` is rejected on streaming but accepted in memory | | M1 | Medium | MWU-vs-scipy correctness tests all `@needs_cuda` | **Fixed** | `test_mwu.py::test_mwu_ref_matches_scipy_cpu`, which cites M1 | | M2 | Medium | Streaming equivalence checked Pearson correlation only | **Fixed** | `test_shard_stream.py::_assert_equiv` — `allclose(rtol=1e-5, atol=1e-7, equal_nan=True)` over full row coverage, with the M2 reasoning at the call site | | M3 | Medium | `environment.yml` pinned `gpudge @v0.2.0` | **Fixed** | pins the current release tag; kept in step with README by a note in both | @@ -51,7 +56,7 @@ Added 2026-08-18. **All 22 findings were addressed in v0.3.1 ([#59](https://gith | N2 | Nit | `.item()` forces per-chunk GPU→CPU syncs | **No change** | a perf nit with no correctness impact; the syncs are still there in `_mwu.py` | | N3 | Nit | A group literally named `'all_others'` is remapped | **No change, deliberate** | this review's own recommendation was "no action before the legacy spelling is removed"; the behaviour is noted in `__init__.py` | | N4 | Nit | `mwu_ref` sentinel test checked only the p-value half | **Fixed** | `test_mwu.py` now asserts `(U[ref_idx] == 0).all()`, citing N4 | -| N5 | Nit | `MeanCalc` / `__version__` absent from the README API docs | **Fixed** | both documented in the README ([#126](https://github.com/ArcInstitute/gpudge_arc/pull/126)) | +| N5 | Nit | `MeanCalc` / `__version__` absent from the README API docs | **Fixed** | both documented in the README (`gpudge_arc#126`) | | N6 | Nit | `csr_row_sums` docstring said "CSR" but accepts dense | **Fixed** | now "Per-row sum of a CSR sparse OR dense matrix" | | N7 | Nit | README/SKILL listed 5 of the 10 default output columns | **Fixed** | both now list all ten under a `columns (10):` heading | diff --git a/docs/reviews/README.md b/docs/reviews/README.md index f4daad2..136d2f0 100644 --- a/docs/reviews/README.md +++ b/docs/reviews/README.md @@ -9,6 +9,10 @@ defect from a live one without cross-referencing the changelog. A findings list without dispositions reads as a list of known, open bugs — the opposite of what publishing it is for. +Issue and PR numbers on this page and in the reports — `gpudge_arc#59` and +similar — are provenance: they identify entries in an issue tracker that is not +public and will not resolve from here. + | report | findings | disposition | |---|---|---| | [2026-06-13](2026-06-13-gpudge-ultrareview.md) | 23 survived verification, of 28 raw | status table in the report: 9 confirmed defects, 5 fixed in the same PR, 4 filed as issues |