fix(release): v1.0.1 — lockstep component publishing: stamp the tag version onto every dist, publish the complete closure (ADR-0053)#186
Merged
officialCodeWork merged 2 commits intoJun 10, 2026
Conversation
…ersion onto every dist, publish the complete closure (ADR-0053) pip install rag-platform could never resolve: the meta pinned 16 component dists at ==1.0.0 but release.yml never built or published any component, one pin named a dist that doesn't exist (ragctl; the workspace dist is rag-ragctl), 15 transitive components were unpinned, the [backends]/[kms] extras referenced extras rag-backends never declared, the metadata-only meta wheel didn't even build (hatchling needs bypass-selection), and workspace versions ranged 0.1.0-0.26.0. The fix (ADR-0053): one lockstep platform version, stamped from the tag. - scripts/stamp_versions.py rewrites every version site (member pyprojects, literal __version__ attrs, the meta + all its == pins); task version:stamp / version:check wrap it. - release.yml resolves the version from the tag (dispatch input for dry runs), stamps, then publishes the complete closure — uv build --all-packages + the meta = 33 dists — via Trusted Publishing; npm stamps the TS SDK (npm version) and Helm stamps the chart (--version / --app-version; published chart version = platform version) in the same run. - The meta pins all 31 components exactly, by real dist name, with extras that exist; in-repo versions are the lockstep baseline (1.0.1). - tests/packaging/test_meta_package.py gates lockstep, closure-completeness, and extras-validity, so a hand-bumped single package cannot merge. - release-please removed: it covered 2 of 32 members, its manifest was frozen at 0.2.0, and its core-v*/gateway-v* tags matched no workflow. The tag is the only version authority (refines ADR-0052 "components version under it via release-please"). Also includes the in-tree gateway version single-sourcing fix (one reported version: __version__ / OpenAPI info.version / GET /v1/info all read the rag-gateway dist metadata via rag_gateway._version; dist/openapi.* + REST reference regenerated; every surface pinned by a new gateway test). Verified end-to-end: all 33 dists build; pip install rag-platform==1.0.1 resolves, installs, imports, and runs ragctl against them; full test suite, ruff, and mypy --strict green. Documentation: docs/adr/ADR-0053-lockstep-component-publishing.md (new), docs/guides/packaging-distribution.md, docs/release-notes/v1.0.1.md, docs/README.md, packaging/README.md, packaging/rag-platform/README.md, docs/ga/ga-readiness-checklist.md, ADR-0049/0052 cross-links, CLAUDE.md, TRACKER.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…aken (rename before first tag)
Independent post-implementation verification of the ADR-0053 lockstep scheme
swept all 33 intended dist names against PyPI: rag-agent, rag-reranker, and
rag-retrieval are already owned by unrelated third-party projects (active
releases 2024-2026, so PEP 541 reclaim is unrealistic). The meta's ==X.Y.Z
pins on those names can never resolve from the real index, and pinning a
third-party-owned name is a dependency-confusion risk; the publish is also
not atomic, so tagging before a rename would publish ~30 dists, fail 3, and
leave rag-platform unresolvable. The other 30 names were verified free, as
were rename candidates: agentcontextos-{agent,reranker,retrieval} (coherent
set), rag-rerank, rag-agent-runtime; rag-retriever is taken.
Recorded as a blocker on the GA checklist's registry first-publish item
(with the verified-free candidates and the mechanical rename recipe), as an
ADR-0053 consequence, and as a caveat on TRACKER's next-action tag cut. The
name choice itself is a product decision, deliberately not made here.
Everything else verified green in the same pass: tests/packaging + full
suite + mypy --strict + ruff + uv lock --check; 33 dists build at 1.0.1;
pip install rag-platform==1.0.1 from those dists resolves, imports, and
runs ragctl version => 1.0.1 in a fresh venv.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
officialCodeWork
merged commit Jun 10, 2026
30c3517
into
fix/v1.0.1-serve-entrypoint
13 of 23 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The bug
pip install rag-platformcould never resolve.packaging/rag-platformpinned 16 component dists at==1.0.0, butrelease.yml's PyPI job only built the meta + the Python SDK — no component was ever published. And the pins couldn't have resolved even if publishing existed:ragctl; the workspace dist israg-ragctl),rag-parsers,rag-query,rag-cache, …) were missing entirely,[backends]/[kms]extras referenced extrasrag-backendsnever declared (pgvector/qdrant/redis/s3/kms-awsare base deps) —rag-platform[backends]silently installed nothing,bypass-selection),==1.0.0,core-v*tags match no workflow trigger.The fix — ADR-0053: one lockstep platform version, stamped from the tag
Keeps ADR-0052's one-platform-version policy and makes the tag the only version authority:
scripts/stamp_versions.py(new) rewrites every version site — each member's[project] version, literal__version__attrs, and the meta's version + all of its==pins.task version:stamp -- X.Y.Z/task version:checkwrap it. In-repo versions are now the lockstep baseline (1.0.1).release.ymlresolves the version from the tag (dispatchversioninput for dry runs, env-indirected), stamps, then builds + publishes the complete closure — 33 dists (31 components +agentcontextos+rag-platform) viauv build --all-packages+ Trusted Publishing. npm stamps the TS SDK (npm version), Helm stamps the chart (--version/--app-version; published chart version = platform version; push now respectsdry_run).tests/packaging/test_meta_package.py(new CI gate): lockstep across all 84 version sites, pin-set == workspace dist set (a new package can't ship unpinned; a rename can't dangle), extras-validity, and stamp idempotency.Also includes the in-tree gateway version single-sourcing fix (one reported version:
__version__/ OpenAPIinfo.version/GET /v1/infoall read therag-gatewaydist metadata;dist/openapi.*+ REST reference regenerated; surfaces pinned by a new gateway test).Verification
uv build --all-packages+ meta), and from a clean venv against those artifacts:pip install rag-platform==1.0.1resolves (144 pkgs),[all]resolves (181), a real install importsrag_gateway/rag_core/ragctlat 1.0.1 and runsragctl.ruff check+format --checkclean,mypy --strictclean, OpenAPI drift gate clean.Documentation
docs/adr/ADR-0053-lockstep-component-publishing.mddocs/guides/packaging-distribution.md(stamping mechanism + cutting-a-release checklist),docs/release-notes/v1.0.1.md,docs/README.md(ADR row + guide row),packaging/README.md,packaging/rag-platform/README.md,docs/ga/ga-readiness-checklist.md(trusted-publisher scope: all 33 dists), ADR-0049/0052 cross-links,CLAUDE.md(lockstep standing constraint),TRACKER.md🤖 Generated with Claude Code