Skip to content

Commit cc8aabe

Browse files
lucapinelloclaude
andauthored
Fold the docs work into 0.7.5 for distribution (#245)
The README restructure, the second de-lecturing pass and the six documentation defects were sitting in [Unreleased] behind an already-tagged 0.7.5. Folded into the [0.7.5] section so what gets distributed as v0.7.5 is the tree people will actually read, rather than a release whose README improves only on main. Ordered chronologically within Documentation rather than newest-first, because the second README pass explicitly refers back to the first. No version bump: this is the same release, re-cut. setup.py, chorus/__init__.py and CITATION.cff stay at 0.7.5, and the [0.7.5] compare link is unchanged. The tag and GitHub Release move with this commit, which means the four traps from the v0.7.3 move all apply again: delete without -q and check the exit code, recreate with --cleanup=verbatim and count the '#' headings back, restore isDraft=false because deleting a tag with a Release demotes it to a draft, and regenerate both copies of the notes from the one CHANGELOG section and hash-compare them. Fast suite 2,144 passed / 35 skipped. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent 721393f commit cc8aabe

1 file changed

Lines changed: 41 additions & 42 deletions

File tree

CHANGELOG.md

Lines changed: 41 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -6,48 +6,7 @@ project adheres to [Semantic Versioning](https://semver.org/).
66

77
## [Unreleased]
88

9-
### Documentation
10-
11-
- **Second README pass: less lecturing.** The first pass moved caveats out of the reading path; this one
12-
cuts explanation a reader does not act on. Gone: the decimal-vs-binary units lesson on the free-disk
13-
bullet ("a volume sold as 100 GB is 93.1 GiB, so it fits with ~2 GiB spare"), ~15 lines on why conda envs
14-
are large (pip hardlinking, `du -sc` semantics), a units note explaining an inconsistency in our own
15-
tables, the provenance of an older audit's equivalence numbers, and the history of the background
16-
downloader's previous fetch rule. Also removed five outright duplications — a comment-only BedGraph code
17-
block that pointed at the real recipe, two ways to load the same genome, `Core concepts` re-defining
18-
"Oracle" and "Track" from `Key terms`, `Key terms` re-defining "Conversational genomics" from the
19-
paragraph three lines above it, and the credentials/conda-env rule stated in two places. Cumulatively
20-
since 0.7.5: aside text **12,229 → 6,409 chars (−48%)**, longest aside 1,692 → 704, prose lines over 420
21-
chars 17 → 8.
22-
23-
One guard was deleted rather than satisfied: `test_the_tldr_install_size_agrees_with_the_disk_table`
24-
existed to keep the TLDR's install size in sync with the disk table, and the TLDR no longer states an
25-
install size, so there was nothing left to keep in sync.
26-
- **README restructured to cut clutter.** It had accumulated **24 blockquote asides totalling 12,229
27-
characters**, the longest 1,692 — caveats and per-release detail interrupting the reading path rather
28-
than living somewhere findable. Now **6,793 characters** (−44%), longest 704. The changes are structural,
29-
not just shorter: one **Caveats** section holds the four things that can change a number (Enformer
30-
cross-process variation, the pre-0.7.5 `alphagenome_pt` splice history, Cherimoya-vs-ChromBPNet
31-
magnitude, hg38-only), with inline asides reduced to pointers; token plumbing moved from the quick start
32-
into the installation section; and per-release detail is delegated to this changelog, so the README stops
33-
growing by a line per release.
34-
- **Six documentation defects fixed**, found auditing notebooks, examples, docs and the nulls:
35-
- `examples/walkthroughs/README.md` described Sei by its **pre-0.7.4 scope** ("40 sequence classes") in a
36-
table the README calls a "full side-by-side comparison" — which also covered only 6 of 8 oracles.
37-
Corrected, with Cherimoya and EPInformer-seq added.
38-
- `docs/variant_analysis_framework.md` still carried the **"1–2 % fp32 noise"** backend-equivalence claim
39-
that 0.7.5 corrected in the README: understated, and false for the `SPLICE_SITES` assay.
40-
- **`describe_tracks()` appeared zero times in `docs/`**, including the "Full Python API reference". Now
41-
documented there with its signature, its load-free guarantees, and what it replaces.
42-
- `docs/BACKGROUND_NULL_PROTOCOL.md` had **no record that `alphagenome_pt` has no null of its own** and
43-
ranks against `alphagenome`'s. New §8b states the alias, the premise, the test that enforces it, and
44-
that the test must be extended before another oracle is aliased. Decision logged for 2026-08-18.
45-
- `examples/notebooks/README.md` said each notebook "produces … outputs inline" while **16 code cells
46-
across three ship blank** — the cells needing a second oracle env or `coolbox`. Now stated.
47-
- The free-disk bullet still said a single-oracle install is "~13 GiB, not 85" after the total moved
48-
to 87.
49-
- Full findings, what was verified clean, and the guard/false-positive notes:
50-
[`audits/2026-08-18_post_v075_docs_and_readme_audit.md`](audits/2026-08-18_post_v075_docs_and_readme_audit.md).
9+
_Nothing yet._
5110

5211
## [0.7.5] — 2026-08-18
5312
### Fixed
@@ -145,6 +104,46 @@ project adheres to [Semantic Versioning](https://semver.org/).
145104
- `TrackRecord.has_background` no longer promises more than it delivers: no oracle populates it, so
146105
the docstring now says so and explains why (`describe_tracks()` stays download-free), pointing
147106
callers at `NormalizationLoader.has_background`.
107+
- **README restructured to cut clutter.** It had accumulated **24 blockquote asides totalling 12,229
108+
characters**, the longest 1,692 — caveats and per-release detail interrupting the reading path rather
109+
than living somewhere findable. Now **6,793 characters** (−44%), longest 704. The changes are structural,
110+
not just shorter: one **Caveats** section holds the four things that can change a number (Enformer
111+
cross-process variation, the pre-0.7.5 `alphagenome_pt` splice history, Cherimoya-vs-ChromBPNet
112+
magnitude, hg38-only), with inline asides reduced to pointers; token plumbing moved from the quick start
113+
into the installation section; and per-release detail is delegated to this changelog, so the README stops
114+
growing by a line per release.
115+
- **Second README pass: less lecturing.** The first pass moved caveats out of the reading path; this one
116+
cuts explanation a reader does not act on. Gone: the decimal-vs-binary units lesson on the free-disk
117+
bullet ("a volume sold as 100 GB is 93.1 GiB, so it fits with ~2 GiB spare"), ~15 lines on why conda envs
118+
are large (pip hardlinking, `du -sc` semantics), a units note explaining an inconsistency in our own
119+
tables, the provenance of an older audit's equivalence numbers, and the history of the background
120+
downloader's previous fetch rule. Also removed five outright duplications — a comment-only BedGraph code
121+
block that pointed at the real recipe, two ways to load the same genome, `Core concepts` re-defining
122+
"Oracle" and "Track" from `Key terms`, `Key terms` re-defining "Conversational genomics" from the
123+
paragraph three lines above it, and the credentials/conda-env rule stated in two places. Cumulatively
124+
since 0.7.5: aside text **12,229 → 6,409 chars (−48%)**, longest aside 1,692 → 704, prose lines over 420
125+
chars 17 → 8.
126+
127+
One guard was deleted rather than satisfied: `test_the_tldr_install_size_agrees_with_the_disk_table`
128+
existed to keep the TLDR's install size in sync with the disk table, and the TLDR no longer states an
129+
install size, so there was nothing left to keep in sync.
130+
- **Six documentation defects fixed**, found auditing notebooks, examples, docs and the nulls:
131+
- `examples/walkthroughs/README.md` described Sei by its **pre-0.7.4 scope** ("40 sequence classes") in a
132+
table the README calls a "full side-by-side comparison" — which also covered only 6 of 8 oracles.
133+
Corrected, with Cherimoya and EPInformer-seq added.
134+
- `docs/variant_analysis_framework.md` still carried the **"1–2 % fp32 noise"** backend-equivalence claim
135+
that 0.7.5 corrected in the README: understated, and false for the `SPLICE_SITES` assay.
136+
- **`describe_tracks()` appeared zero times in `docs/`**, including the "Full Python API reference". Now
137+
documented there with its signature, its load-free guarantees, and what it replaces.
138+
- `docs/BACKGROUND_NULL_PROTOCOL.md` had **no record that `alphagenome_pt` has no null of its own** and
139+
ranks against `alphagenome`'s. New §8b states the alias, the premise, the test that enforces it, and
140+
that the test must be extended before another oracle is aliased. Decision logged for 2026-08-18.
141+
- `examples/notebooks/README.md` said each notebook "produces … outputs inline" while **16 code cells
142+
across three ship blank** — the cells needing a second oracle env or `coolbox`. Now stated.
143+
- The free-disk bullet still said a single-oracle install is "~13 GiB, not 85" after the total moved
144+
to 87.
145+
- Full findings, what was verified clean, and the guard/false-positive notes:
146+
[`audits/2026-08-18_post_v075_docs_and_readme_audit.md`](audits/2026-08-18_post_v075_docs_and_readme_audit.md).
148147

149148
## [0.7.4] — 2026-08-17
150149

0 commit comments

Comments
 (0)