docs: trim the 0.10.0 changelog entry - #54
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| - Known issue: a vector index is not yet used by the query planner on a managed | ||
| database. Reproduces via the CLI, so it is engine-side; BM25 is unaffected. |
There was a problem hiding this comment.
super nit: (not blocking) This bullet sits under ### Added, so it reads as "Added: Known issue". The repo otherwise sticks to the Keep a Changelog categories (Added/Changed/Fixed/Removed). Folding it into the create_index bullet as a trailing sentence, or giving it its own ### Known issues subheading, keeps the section headings meaning what they say.
Also, the original wording anchored the observation in time ("when this version was released"); the trimmed present tense ("is not yet used") will silently go stale once the engine fixes it. The dated ## [0.10.0] heading covers this well enough for a changelog, but "as of this release" would make it explicit at no cost in length.
There was a problem hiding this comment.
Docs only. Verified the trimmed entry against the source: every claim it makes is accurate, and everything cut is still documented where the PR description says it is — index_name derivation, both vector modes, the metric→distance-function mapping, and the ValueError rules are all in create_index's docstring (hotdata_framework/client.py:478-532) and CONTRACT.md:67. CreateIndexResult is exported (hotdata_framework/init.py:13,47) and listed in the contract surface. One super nit inline.
Note on CI: only "Check release metadata" had reported at review time; the Python 3.12 test job was still pending, so I can't speak to it.
| in the CLI. The build is a background job whose submit call reports success even | ||
| when the build later fails, so this polls the job and raises `RuntimeError` with | ||
| its error message; `wait=False` returns as soon as the job is accepted. Returns | ||
| `CreateIndexResult`, also exported. |
There was a problem hiding this comment.
nit: (not blocking) The last commit (86aab61) drops the vector-planner caveat, and after it that limitation is recorded nowhere in the repo. I grepped for it — client.py:67-71 and CONTRACT.md:67 document only the metric mismatch fallback (cosine index vs. l2_distance query), which is a different failure; nothing mentions that a correctly-matched vector index on a managed database still isn't picked up by the planner.
The docstring now reads the other way: client.py:486-487 says vector queries "work without one, but only at full-scan speed", which tells a reader that building the index buys acceleration — the exact expectation the caveat existed to correct.
Two things follow. The PR description still lists "the vector-planner caveat" as one of the three things this entry keeps, so it no longer matches the diff. And if the caveat is going to leave the changelog, the natural home for it is the index_type paragraph in the create_index docstring, next to the full-scan sentence it qualifies — one clause, e.g. "on a managed database the planner does not currently use a vector index, so those queries stay correct but unaccelerated". Trimming the changelog is a fair call; dropping the only record of the limitation is a separate decision, and I don't think it was the intended one.
The entry ran 46 lines for a single added method, against neighbouring entries of 3-10 (0.9.0 = 10, 0.8.0 = 6, 0.7.2 = 3). Trimmed to 6. Keeps what a reader scanning the changelog needs: what the method is, and that it polls the build job because the submit call reports success even when the build later fails. Everything cut is already documented in the create_index docstring, CONTRACT.md, and #53.
86aab61 to
1b47739
Compare
There was a problem hiding this comment.
Docs-only changelog trim. The remaining entry is accurate against create_index's behaviour (background job, poll-then-raise, wait=False, CreateIndexResult export), the ## [0.10.0] - 2026-08-07 heading and surrounding entries are intact, and no version bump means check-release.py stays a no-op. No blocking issues.
1 participant
Trims the
0.10.0changelog entry from 46 lines to 6. Docs only —CHANGELOG.mdis the single file touched.The entry was written at the length of a design document, against neighbouring entries of 3–10 lines (0.9.0 = 10, 0.8.0 = 6, 0.7.2 = 3).
Kept: what
create_indexis, and that it polls the build job because the submit call reports success even when the build later fails — the one genuinely surprising behaviour.Cut: the metric→distance-function mapping, both vector-index modes, the
index_namederivation, the enumerated validation rules, and the verification write-up. All of that already lives in thecreate_indexdocstring,CONTRACT.md, and #53.Also cut: a note about the query planner not using a vector index on a managed database. That describes RuntimeDB's behaviour, not this package's — it did not change in 0.10.0, and nobody would come back to amend this entry when the engine changes. It is being taken to the
datafusion-vector-search-extrepo instead, where it can be diagnosed and closed.Not part of this PR
No version bump, so
check-release.pyis a no-op and nothing republishes. The GitHub Release body forv0.10.0has been re-synced from this trimmed entry usingscripts/extract-changelog.py, so the two stay byte-identical. The published 0.10.0 sdist keeps its own copy of the longer entry — PyPI artifacts are immutable — and the PyPI page is unaffected either way, since it rendersREADME.md.