Skip to contents

v0.1 release-engineering preparation checklist (the non-blocking preparation batch)

Source: vignettes/articles/release-v0.1-checklist.qmd

HISTORICAL SNAPSHOT — state as of 2026-09-30. For current status see NEWS.md / vignettes/articles/roadmap.qmd. Later corrections are appended in place as dated [2026-10-13: …] notes; the body is otherwise preserved verbatim. (English rendering prepended by the corpus pass 2026-10-13; the Chinese original follows below, byte-preserved incl. its dated errata notes.)

Status: preparation – the actual release waits for the M1s acceptance-gate caliber adjudication (the author’s call). This document was produced by the release-engineering preparation unit (2026-09-30), basis: the ROADMAP v3 v0.1 release gate (vignettes/articles/roadmap.qmd, the M1s acceptance row), ADR 0002 §3.3 (the vendor generated at release time), NEWS.md, the existing conventions of .github/workflows/ci.yml, and this batch’s smoke-drill record (§4). Discipline: this batch bumps no version, tags nothing, pushes nothing, enables no workflow.

1. The milestone acceptance state (the v0.1 release gate)

The milestone The state The basis / open items
M0 the engineering foundations ✅ 10/10 check 0 error / 0 warning / 1 NOTE; the S7 validations, the RNG golden and the vendor numbers into the ADRs all pass (vignettes/articles/2026-09-28-M0-*.md)
M1s the engine and the catalog ⏸ 13/14 the sole open item: the catalog/NMF speed caliber. Measured (vignettes/articles/devlog-2026-09-30-M1s-13-bench.qmd): the SBS96 10⁶ catalog 2.6× SPMG (3.73s, <5s ✓), the NMF KL 2.3× R NMF brunet (a C core), the NNLS 1.8× scipy – inconsistent with the 50×/100×/10× hardwired in the ROADMAP. The PI re-review’s root cause: the multipliers were written against an unmeasured baseline (brunet is a C kernel; SPMG on clean input is numpy-vectorised); against the real genome + the full-pipeline caliber 50× may hold (the dense arm SPMG 46s). Re-calibrating the budget caliber touches ROADMAP wording, awaiting the author’s adjudication; after the ruling the gate = (an optional parallel-tally optimisation) + the sigminer/MP toy cross-validation close-out. The correctness anchors pass: the 10⁶ mutations agree cell by cell with SPMG; all fixtures green.
M1c the catalog completeness + ID83 ✅ 4/4 (delivered early) the former v0.2 scope delivered early (the ID83 golden + the GMM stratifier). Whether to fold it into v0.1 = an author decision item: folding it in requires NEWS.md / README / the Release notes to gain the ID83 and ms_stratify_hypermutants entries, and its uncommitted work unit (see §8 P3-1) must first land

2. The version decision

  • Then-current Version: 0.0.0.9000 (likewise in the NEWS.md title). The release actions (executed after the M1s gate closes, not done by this batch):
    1. DESCRIPTION Version: 0.1.0; the NEWS.md title becomes # msuiter 0.1.0 plus the release date and (if the ruling folds it in) the M1c entries;
    2. the README installation-section finish (§6);
    3. the tag v0.1.0 (see §7);
    4. right after the tag, trunk bumps back to 0.1.0.9000 to open the new development cycle, and the NEWS head starts a # msuiter 0.1.0.9000 (development version) section.

3. The deliverables list

The deliverable The state The essentials
The source tarball ✅ the flow drilled R CMD build produces msuiter_0.0.0.9000.tar.gz (2,604,302 B; the drill artifact sits in a scratch directory and is not committed; the real release re-runs after the version bump). vendor.tar.xz is attached per the release-time generation discipline (§4 step 2; ADR 0002 §3.3, never entering git)
the GitHub Release ⏳ awaiting release the trigger = the tag push (the workflow proposal draft .github/workflows/release.yml, moved to .github/workflows/release.yml before enabling). The Release-notes draft essentials (extracted from NEWS.md): the Rust compute kernel + the stateless FFI (the 6 msffi_* hard-contract probes: column-major / the NA line of defense / Result→condition / interrupts / the per-call thread pool); the S7 object model’s 7 classes (MsVariants/MsCatalog/MsSignature/MsFit/MsRefDb/MsEngine/MsBenchmark); the channel-registry single source of truth (SBS96/192/384/1536 + DBS78 + the MNV routing); the self-developed PCG64+SplitMix64 RNG (no rand dependency); the workflow grammar’s three rings ms_variants() → ms_tally() → ms_extract() (the KL-NMF single method, deterministic, thread-invariant); the dependency budget frozen (vendor.tar.xz ≈ 1.71 MB baseline – before release the ADR increment row per §7 P1-2 has been added); MSRV rustc ≥ 1.71, R ≥ 4.3, Imports only S7 + rlang; (if folded in) the ID83 channels + the GMM hypermutator stratifier
The three-OS binaries ⏳ the draft ready the macOS arm64 / Linux / Windows matrix (release.yml-draft.yml); r-universe will also build binaries automatically, the GitHub Release binaries are the redundant fallback (the ROADMAP M8 close-out, before CRAN)

4. The smoke-drill record (executed by this batch; all drill artifacts under a scratch directory, none committed)

  1. R CMD build (carrying the uncommitted GMM-stratify working state on the tree): the tarball 2,604,302 B, the build clean (logs: the empty logs/ directory auto-pruned).
  2. The vendor generation: sh tools/vendor.sh → /tmp/msuiter-vendor.tar.xz (1,863,340 B) → copied to src/rust/vendor.tar.xz (covered by gitignore; deleted after the install; the working tree restored). --check reports DRIFT (see §8 P1-1).
  3. The CRAN-mode installation (a clean scratch library, installed from the tarball): env -u NOT_CRAN -u DEBUG R CMD INSTALL msuiter_0.0.0.9000.tar.gz -l <scratch-lib> → exit 0, a 27.9 s wall clock (the cargo release library 13.3 s). The log’s evidence chain complete: Building for CRAN → === Using offline vendor tarball === → cargo build -j 2 --offline --lib --release → --print=native-static-libs → the rust_clean cleanup of .cargo/vendor/target → DONE (msuiter). Zero warnings.
  4. Dependency resolution: R CMD INSTALL does not install Imports – in the clean library the first library() fails for the missing S7/rlang; passing after installing S7 0.2.2 / rlang 1.3.0. The r-universe/CRAN users are covered by automatic dependency resolution, no risk; but the Release verification script must first install.packages(c("S7","rlang")).
  5. The end-to-end smoke (smoke.R, self-constructing minimal data in the script, independent of tests/): an inlined little-endian 2bit writer writes the synthetic genome (chr1 ACAC… 64 bp incl. an N block, chr2 GCGC… 40 bp) → 41 two-sample SNVs (SA: mostly C>A / SB: mostly C>G) → ms_variants() → ms_tally(mode="SBS96") (96×2, n_skipped=0) → ms_extract(k=2) → the MsSignature’s seven fields complete (the signatures 96×2 colSums=1, the exposures 2×2, catalog_summary’s n_channels/n_samples/channel_name/channel_hash/build, engine=“nmf”, seed=1, stability, k_evidence); the reconstruction error = 0 (signatures %*% exposures vs counts); the re-fit identical = TRUE (the determinism anchor). SMOKE PASS.

5. Installable from r-universe (the acceptance gate)

The mechanism: r-universe builds from the GitHub repository automatically – after the author-side one-time actions, every push yields the source + binary packages automatically. The author’s action list:

6. The tag / branch strategy and the closing items

  • The tag: v0.1.0 (annotated), on main after the §2 version actions; never on a dirty tree – the parallel units must first land/be committed (§8 P3-1).
  • The README finish before the tag: the installation section (the source-install path = remotes::install_github("...") with the rustc≥1.71 hint + the r-universe path), the badges, and the examples synchronized with the NEWS.
  • The NEWS finish before the tag: the release date, the (if folded-in) M1c entries; a known-issues section optional.
  • The CI/release.yml: before enabling, move the draft into .github/workflows/release.yml and verify the actions versions and the dependabot coverage.
  • The G-gate reminder: G1 (the co-maintainer) hangs before M1s in the ROADMAP – before the v0.1 release is the last costless enrollment window (an author decision item).

7. The author decision items summed (every adjudication blocking the release)

  1. The M1s speed-caliber re-calibration (the sole 13/14 gap; the ruling written back into the ROADMAP + the ADR/bench memo);
  2. whether M1c folds into v0.1 (affecting the NEWS/README/Release notes and the tag content);
  3. the vendor baseline update (P1-2, a mechanical action, done along the way after the caliber ruling).

8. The outstanding known items (the P-level list)

The level The item The owner
P1-1 the M1s speed caliber awaiting adjudication – the v0.1 release gate itself (§1, §7.1) the author
P1-2 tools/vendor.sh --check red: the ADR 0002 baseline expired. Measured uncompressed 17,238,305 B vs the baseline 12,526,058 (+37.6%); the tar.xz 1,863,340 vs 1,407,588; the Cargo.lock now 33 entries (the baseline 24 crates). The baseline’s last increment row stops at 2026-09-28 U-M0-09 (rayon); the Cargo.lock’s later evolution (the lock’s last landing point the U-M1s-09 commit) did not gain the increment rows per the ADR 0002 “increment record” discipline. Not introduced by this batch (the lock agrees with HEAD). Must before the release: re-run the vendor three calibers → append the ADR 0002 increment rows → update the vendor.sh constants → --check turns green; or trigger the dependency-re-shrinking decision (ARCH §11) the release batch
P2-1 the LICENSE NOTE (the Apache License (>= 2.0) + file LICENSE restrictions NOTE under --as-cran) – classified as a CRAN-submission-time handling item; v0.1 going via r-universe/GH Release is unaffected M8 (vignettes/articles/devlog-2026-09-29-M0-07-08.qmd)
P2-2 checkbashisms: an environmental WARNING from the –as-cran depending on a runner’s optional tool; the check-r-package error_on=error ruling sidesteps it the M8 rhub/win-builder pre-submission (the same devlog)
P2-3 the CODECOV_TOKEN secret unset, the coverage upload silently skipped; the Rust coverage unwired; the R≥85% gate deferred a one-time action on the repository settings page (the same devlog)
P2-4 the check-context skip guards: the repository drift-guard tests skip in the R CMD check context (sysdata/source-tree access); the CI guards job’s repo-mode testthat carries them (wired, the ci.yml guards) status quo kept, the U-M0-07 handover list solidified (vignettes/articles/devlog-2026-09-28-M0-05.qmd)
P3-1 the parallel GMM-stratify work unit uncommitted (R/stratify.R, src/rust/src/stratify.rs etc.) – a build from the tree carries the working state; must land before the tag the parallel unit + the release batch
P3-2 the install-time Rust toolchain unpinned: tools/msrv.R only gates MSRV≥1.71; the local drill actually resolved to rustc 1.92.0 (≠ the shell default 1.97.1) with no rust-toolchain.toml. Affects the binary reproducibility / the r-universe build consistency; optionally pin it or accept the MSRV-gate semantics later (may enter M8)
P3-3 the SBS192/384 bench on the real genome + transcript annotation (the PR #256 semantics fork) and the parallel-tally optimisation the M1c/M7 lists (vignettes/articles/devlog-2026-09-30-ID83-design-memo.qmd)

v0.1 发布工程预备清单（非阻塞预备批）

HISTORICAL SNAPSHOT — state as of 2026-09-30. For current status see NEWS.md / vignettes/articles/roadmap.qmd. Later corrections are appended in place as dated [2026-10-13: …] notes; the body is otherwise preserved verbatim.

状态：预备——正式发布等 M1s 验收门口径裁决（作者拍板）。本文档由发布工程预备单元生成（2026-09-30）， 依据：ROADMAP v3 v0.1 发布门（vignettes/articles/roadmap.qmd M1s 验收行）、ADR 0002 §3.3（vendor 发布期生成）、 NEWS.md、.github/workflows/ci.yml 既有约定，及本批冒烟演练实录（§4）。 纪律：本批不 bump 版本、不打 tag、不 push、不启用 workflow。

1. 里程碑验收状态（v0.1 发布门）

里程碑 状态 依据 / 待决项
M0 工程地基 ✅ 10/10 check 0 error / 0 warning / 1 NOTE；S7 校验、RNG golden、vendor 数字入 ADR 均过（vignettes/articles/2026-09-28-M0-*.md）
M1s 引擎与目录 ⏸ 13/14 唯一待决：目录/NMF 速度口径。实测（vignettes/articles/devlog-2026-09-30-M1s-13-bench.qmd）：SBS96 10⁶ 目录 2.6× SPMG（3.73s，<5s ✓）、NMF KL 2.3× R NMF brunet（C 核）、NNLS 1.8× scipy——与 ROADMAP 写死的 50×/100×/10× 不符。PI 复核根因：倍数写于未实测基线（brunet 是 C 内核、SPMG 干净输入是 numpy 向量化）；对真实基因组 + 全管线口径 50× 或成立（dense 臂 SPMG 46s）。预算口径重校准触及 ROADMAP 措辞，待作者裁决；裁决后门 = （可选并行 tally 优化）+ sigminer/MP 玩具交叉验证收口。正确性锚已过：10⁶ 变异 SPMG 逐格一致；夹具全绿。[2026-10-13: closed – PI 方案A ruling 2026-10-05; vignettes/articles/roadmap.qmd:51 now records “M1s 14/14 ✅ 关闭”（50×/100×/10× rhetoric moved to the naive-implementation baseline）]
M1c 目录完备 + ID83 ✅ 4/4（提前完成） 原 v0.2 范围提前交付（ID83 golden + GMM 分层器）。是否并入 v0.1 = 作者决策项：并入则 NEWS.md / README / Release notes 需补 ID83 与 ms_stratify_hypermutants 条目，且其未提交工作单元（见 §8 P3-1）须先落定

2. 版本决策

  • 当时 Version: 0.0.0.9000（NEWS.md 标题同）[2026-10-13: snapshot-time version; v0.1.0 has since shipped (2026-10-05, see NEWS.md) and trunk now reads 0.1.0.9000]。发布动作（M1s 门关闭后执行，本批未做）：
    1. DESCRIPTION Version: 0.1.0；NEWS.md 标题改 # msuiter 0.1.0 并补发布日期与（若裁决并入）M1c 条目；
    2. README 安装节收尾（§6）；
    3. tag v0.1.0（见 §7）；
    4. tag 后主干立即 bump 回 0.1.0.9000 开新开发周期，NEWS 顶部另起 # msuiter 0.1.0.9000（开发版）节。

3. 交付物清单

交付物 状态 要点
源码 tarball ✅ 流程已演练 R CMD build 产出 msuiter_0.0.0.9000.tar.gz（2,604,302 B，演练产物在临时目录不入库；正式发布在版本 bump 后重跑）。vendor.tar.xz 按发布期生成纪律附入（§4 步骤 2；ADR 0002 §3.3，永不入 git）
GitHub Release ⏳ 待发布 触发 = tag push（workflow 建议稿 .github/workflows/release.yml，启用前移入 .github/workflows/release.yml）[2026-10-13: superseded – the workflow is live at .github/workflows/release.yml; the draft path no longer exists]。Release notes 草案要点（自 NEWS.md 提取）：Rust 计算核 + 无状态 FFI（6 个 msffi_* 硬契约探测器：列主序 / NA 防线 / Result→condition / 中断 / per-call 线程池）；S7 对象模型 7 类（MsVariants/MsCatalog/MsSignature/MsFit/MsRefDb/MsEngine/MsBenchmark）；通道注册表单一事实来源（SBS96/192/384/1536 + DBS78 + MNV 路由）；自研 PCG64+SplitMix64 RNG（无 rand 依赖）；工作流文法三环 ms_variants() → ms_tally() → ms_extract()（KL-NMF 单方法、确定性、线程不变）；依赖预算冻结（vendor.tar.xz ≈ 1.71 MB 基线——发布前已按 §7 P1-2 补 ADR 增量行）[2026-10-13: aligned to the ADR 0002 MSRV-pinned value 1,744,176 B (vignettes/articles/adr-0002-vendor-budget.qmd §2, the 2026-10-05 baseline re-anchor row); the 1,863,340 B in §4/§8 is this batch’s local-toolchain smoke measurement, kept verbatim]；MSRV rustc ≥ 1.71、R ≥ 4.3、Imports 仅 S7 + rlang；（若并入）ID83 通道 + GMM 超突变分层器
三 OS 二进制 ⏳ 草稿就绪 macOS arm64 / Linux / Windows matrix（release.yml-draft.yml）[2026-10-13: now live as .github/workflows/release.yml]；r-universe 亦会自动产二进制，GitHub Release 二进制是冗余兜底（ROADMAP M8 收口 CRAN 前）

4. 冒烟演练实录（本批执行，演练产物全在临时目录，未入仓库）

  1. R CMD build（含树上未提交的 GMM stratify 工作区状态）：tarball 2,604,302 B，build 干净（logs：空目录 logs/ 被自动剔除）。
  2. vendor 生成：sh tools/vendor.sh → /tmp/msuiter-vendor.tar.xz（1,863,340 B）→ 复制到 src/rust/vendor.tar.xz（gitignore 已覆盖，装后已删除，工作树还原）。--check 报 DRIFT（见 §8 P1-1）。
  3. CRAN 模式安装（干净临时库，从 tarball 装）：env -u NOT_CRAN -u DEBUG R CMD INSTALL msuiter_0.0.0.9000.tar.gz -l <临时库> → exit 0，27.9 s 墙钟（cargo release 库 13.3 s）。日志证据链齐：Building for CRAN → === Using offline vendor tarball === → cargo build -j 2 --offline --lib --release → --print=native-static-libs → rust_clean 清理 .cargo/vendor/target → DONE (msuiter)。零 warning。
  4. 依赖解析：R CMD INSTALL 不装 Imports——干净库缺 S7/rlang 首跑 library() 失败；补装 S7 0.2.2 / rlang 1.3.0 后通过。r-universe/CRAN 用户由自动依赖解析覆盖，无风险；但 Release 验证脚本须先 install.packages(c("S7","rlang"))。
  5. 端到端冒烟（smoke.R，脚本内自造最小数据、不依赖 tests/）：内联小端 2bit writer 写合成基因组（chr1 ACAC… 64 bp 含 N 块、chr2 GCGC… 40 bp）→ 41 条双样本 SNV（SA: C>A 为主 / SB: C>G 为主）→ ms_variants() → ms_tally(mode="SBS96")（96×2，n_skipped=0）→ ms_extract(k=2) → MsSignature 七字段齐（signatures 96×2 colSums=1、exposures 2×2、catalog_summary n_channels/n_samples/channel_name/channel_hash/build、engine=“nmf”、seed=1、stability、k_evidence）；重构误差 = 0（signatures %*% exposures vs counts）；重复拟合 identical = TRUE（确定性锚）。SMOKE PASS。

5. r-universe 可安装（验收门）

机制：r-universe 从 GitHub 仓库自动构建——作者侧一次性动作后，每次 push 自动出 sourc + 二进制包。作者动作清单：

6. tag / 分支策略与收尾项

  • tag：v0.1.0（annotated），打在 main 于 §2 版本动作之后；不打在脏树——先落定/提交并行单元（§8 P3-1）。
  • tag 前 README 收尾：安装节（源码安装路径 = remotes::install_github("...") 需 rustc≥1.71 提示 + r-universe 路径）、badges、示例与 NEWS 同步。
  • tag 前 NEWS 收尾：发布日期、（若并入）M1c 条目、known-issues 节可选。
  • CI/release.yml：启用前把草稿移入 .github/workflows/release.yml 并核对 actions 版本与 dependabot 覆盖。
  • G 门提示：G1（co-maintainer）在 ROADMAP 中挂 M1s 前——v0.1 发布前是最后无成本挂名窗口（作者决策项）。

7. 作者决策项汇总（阻塞发布的全部裁决）

  1. M1s 速度口径重校准（唯一 13/14 缺口；裁决写回 ROADMAP + ADR/bench 备忘）；
  2. M1c 是否并入 v0.1（影响 NEWS/README/Release notes 与 tag 内容）；
  3. vendor 基线更新（P1-2，机械动作，裁决口径后顺手做）。

8. 遗留已知项（P 级清单）

级别 项 归口
P1-1 M1s 速度口径待裁决——v0.1 发布门本体（§1、§7.1） 作者
P1-2 tools/vendor.sh --check 红：ADR 0002 基线过期。实测未压缩 17,238,305 B vs 基线 12,526,058（+37.6%）；tar.xz 1,863,340 vs 1,407,588；Cargo.lock 现 33 项（基线 24 crates）。基线最后增量行停留在 2026-09-28 U-M0-09（rayon），其后 Cargo.lock 演进（lock 最后落点 U-M1s-09 提交）未按 ADR 0002「增量记录」纪律补行。非本批引入（lock 与 HEAD 一致）。发布前必须：重跑 vendor 三口径 → ADR 0002 追加增量行 → vendor.sh 常量更新 → --check 转绿；或触发依赖再收缩决策（ARCH §11） 发布批
P2-1 LICENSE NOTE（Apache License (>= 2.0) + file LICENSE 在 --as-cran 下的 restrictions NOTE）——已定性为 CRAN 提交期处理项，v0.1 走 r-universe/GH Release 不受影响 M8（vignettes/articles/devlog-2026-09-29-M0-07-08.qmd）
P2-2 checkbashisms：–as-cran 依赖 runner 可选工具的环境性 WARNING，check-r-package error_on=error 已裁决规避 M8 rhub/win-builder 预提交（同上 devlog）
P2-3 CODECOV_TOKEN secret 未设，coverage 上传静默跳过；Rust 覆盖率未接线；R≥85% 门后置 仓库设置页一次性动作（同上 devlog）
P2-4 check 语境 skip 守卫：仓库漂移守卫测试在 R CMD check 语境 skip（sysdata/源树访问），CI guards 作业的仓库模式 testthat 承接（已接线，ci.yml guards） 维持现状，U-M0-07 交接清单已固化（vignettes/articles/devlog-2026-09-28-M0-05.qmd）
P3-1 并行 GMM stratify 工作单元未提交（R/stratify.R、src/rust/src/stratify.rs 等）——树上 build 会携带工作区状态；tag 前必须先落定 并行单元 + 发布批
P3-2 安装期 Rust 工具链非钉定：tools/msrv.R 只做 MSRV≥1.71 门，本机演练实际解析到 rustc 1.92.0（≠ shell 默认 1.97.1），无 rust-toolchain.toml。对二进制可复现性/r-universe 构建一致性有影响，可选钉定或接受 MSRV 门语义 后续（可入 M8）
P3-3 真实基因组 + 转录注解下的 SBS192/384 bench（PR #256 语义分叉）与并行 tally 优化 M1c/M7 清单（vignettes/articles/devlog-2026-09-30-ID83-design-memo.qmd）