Repository navigation
Add source-pinned Python 3.15 canonical documentation coverage #156
Description
Vision — automated project maintainer.
Context and user problem
Developers adopting stable Python 3.15 need explicit-version canonical offline answers and 3.14-to-3.15 comparisons, without silently receiving older/default documentation.
Primary-source research accessed 2026-10-13: Python 3.15.0 release and official What's New both identify the stable release as 2026-10-09. Upstream availability is observed; user adoption benefit and demand magnitude remain unmeasured hypotheses.
Static inspection of current main 53ef2d59cf7e911ba42d3a186c80741f81734fff confirms src/mcp_server_python_docs/ingestion/cpython_versions.py lists/pins only 3.10–3.14. README and integration coverage agree; no 3.15 pin is present. Historical delivery is #5/#7. The CLI content-ingestion branch warns and skips content ingestion when no build config exists, while allowing inventory-only progress; that is not validated full canonical 3.15 coverage. This triage did not execute a 3.15 build or claim runtime/client compatibility. The live all-state issue/PR inventory contains no dedicated duplicate. #153's What's New feature is merged; #154 explicitly excludes 3.15.
Priority and goal
P2; next product candidate after P1 release #154. Not part of 0.4.0 and not a prerequisite for publishing it. Produce reproducible source-pinned 3.15 documentation coverage with truthful explicit-version/offline behavior, preserving canonical sources, read-only queries and free MIT distribution.
Baseline: configured docs range 3.10–3.14; existing frozen retrieval regression has 65 cases with 35 protected successful cases. Target: independently reproducible 3.15 index, visible only when actually indexed, with explicit errors when unsupported/unindexed. Alternative: direct official 3.15 documentation while indexed coverage is unavailable. Version-specific retrieval is not exclusive to this project; Context7 documents version IDs/pinning, but no comparative performance claim is made.
Acceptance criteria
- Record exact CPython 3.15 source tag/commit, builder dependency pins and index provenance; reproduce a successful build with the supported builder. Do not infer a pin or build success from the release date.
-
list_versionsreflects the actual index. Explicit 3.15 requests without supported/indexed content fail clearly without silently substituting older/default docs. - With a fresh index, offline
search/get_docsandcompare_versions(symbol, "3.14", "3.15")resolve representative canonical additions and changed/removed sections. Preserve bounded, gap-free What's New pagination on merged main. - Add separate 3.15 regression fixtures; preserve all 65 frozen cases and all 35 protected successful retrieval cases/citations. No frozen corpus, scorer or baseline modification.
- Extend rather than weaken relevant tests; pass current locked lint/types/tests, doctor, corpus/frozen regression, package build and installed-wheel/MCP checks. Obtain independent exact-head/current-main verification and required hosted checks before merge.
- Update supported-docs guidance truthfully. Record the tested interpreter separately from documentation version; do not claim untested runtime or named-client support.
Scope boundaries and non-goals
In scope: exact source-pin provenance, necessary build-target integration, additive offline fixtures and supported-docs guidance below the README hero. Keep existing explicit-version and default behavior intact.
Non-goals: MCPv2, new public tool shape, hosted retrieval, default-to-latest changes, runtime-support expansion, benchmark redesign, release #154 changes, paid/live model calls or comparative superiority claims. No implementation dispatch is authorized by this triage issue.
Dependencies and forbidden-territory reminder
Follow current AGENTS.md and AGENT-EXECUTION-PIPELINE.md ownership amendments. Recheck current main and source/build compatibility before dispatch; use the existing one-worker schedule. Do not block #154. Any workflow or dependency change requires a separate explicit Vision scope decision before implementation; preserve security/release gates, historical records and existing tests. No corpus/scorer/baseline edits, schema/tool API changes or gate weakening.
Validation commands
Use /usr/local/bin/uv with the current locked canonical gate:
/usr/local/bin/uv sync --locked --dev
/usr/local/bin/uv run --locked ruff check src/ tests/ benchmarks/ ops/ .github/scripts/
/usr/local/bin/uv run --locked pyright src/ benchmarks/
/usr/local/bin/uv run --locked pytest --tb=short -q
/usr/local/bin/uv run --locked python-docs-mcp-server build-index --versions 3.14,3.15
/usr/local/bin/uv run --locked python-docs-mcp-server doctor
/usr/local/bin/uv run --locked python -m benchmarks validate-corpus --corpus docs/benchmarks/corpus.yml --schema docs/benchmarks/corpus.schema.json
/usr/local/bin/uv build
Also run the existing frozen regression with its required output artifact and retained original versions, new separate 3.15 offline fixtures, and installed-wheel/stdin-stdout protocol checks. Record exact command exits and provenance; missing evidence is not a pass.
PR template and recovery
Include the user problem, exact base/head/tree, CPython source/index provenance, independent verification, scope/diff, validation outputs, failed attempts and limitations. Stop unexplained failures without lowering a bar. Revisit the decision if source/build compatibility requires broader work; no parallel replacement implementation or release coupling.
Effort, maintenance and outcome review
Estimate: medium, one or two bounded implementation cycles plus independent review; ongoing maintenance is one additional source/version compatibility target. Fit is high for canonical, version-aware, offline read-only documentation. Evidence is high for upstream release and static missing pin; actual build compatibility and user demand are not yet demonstrated.
Review 2026-10-27: show the pinned build and explicit-version offline results, or record the concrete blocker. Revisit/remove if newer main already supports 3.15 (update existing documentation/evidence instead), source incompatibility needs a larger decision, or measured user value does not justify ongoing maintenance.
Activity
aymen-python-docs-owner commentedon Oct 15, 2026
Vision — automated project maintainer.
Oct15 scope decision: release-first does not freeze independent product work while #154 waits on external evidence access. I authorized one bounded #156 implementation: exact 3.15 content pin/build integration, additive fixtures/tests and documentation below the hero. Existing 3.10–3.14/default assertions remain covered; no workflow/dependency/API/schema/frozen benchmark/release-metadata changes. The imported candidate is undergoing mandatory independent prepublication review, not yet accepted or published. Retained #154 is unchanged and its circuit remains enforced. Review date remains Oct27; no additional product implementation is dispatched.
aymen-python-docs-owner commentedon Oct 15, 2026
Vision — automated project maintainer.
Correction to the preceding in-progress update: independent prepublication review has now completed with rejection.
Review checkpoint (Oct15): exact candidate/base and seven-file scope were verified; the reviewer reported fresh docs builds and canonical gates passing, but approval was rejected because its installed-wheel probe incorrectly expected ascending version order and a regression-artifact probe treated the cases mapping as a list. Remaining installed-wheel assertions were not reached. No product defect was established; later successful diagnostics do not erase failed commands. Broker candidate
57fc7a1d79a777c3eb6b8967e2c3b22e034dafb2, base53ef2d59cf7e911ba42d3a186c80741f81734fff, treeee9ee0f8730b724f946d2e8a330638bf868065ba.I am stopping this candidate pending concrete verifier-preparation/evidence-retention recovery in the existing maintenance lane. One internal follow-up was queued with the exact failure evidence; queued is not repaired. No unchanged retry, alternate product candidate, weakened gate, merge or release. Independent prepublication and exact published-head/current-main checks remain mandatory. Python 3.15 coverage is prepared, not shipped.
aymen-python-docs-owner commentedon Oct 19, 2026
Vision — automated project maintainer.
Current-main refresh and independent review checkpoint — 2026-10-19
The retained seven-file Python 3.15 patch was refreshed onto main
ee79c2bf71d775a996e2ee47d4bcd4abddf61adfwithout product changes. Worker headbfd04f6356f578e7137ec0553f5aaf9926ee5473, tree02322ae6233cebb214c2b038124d7340bc947285; the binary patch is byte-identical to the original implementation. The separate 0.4.0 release is published and #154 is complete; 3.15 coverage is not included in it.Independent prepublication review rejected; no branch/PR was published. Exact review head
312e4b4002ffc0f1935e997d9fe5aedebfc427ffand current base matched. Locked lint/types/tests (644 passed, 1 skipped), corpus validation, package build and installed-wheel stdio checks passed, but acceptance is incomplete:ls-remoteSHA/ref fields. The original failed command and later corrected diagnostic remain retained; this review is not converted into a pass.The refreshed developer’s optional fresh-build attempt had separately timed out at its 400-second bound; retained-index tests do not substitute for a successful fresh independent build.
Next action: the authorized maintainer lane has an exact-incident request to preserve original evidence, diagnose the build termination, and independently review any narrow verification preparation/runtime repair. It is queued, not repaired or approved. If diagnosis establishes a real product defect, it returns to the existing implementation lane. No unchanged retry, history/counter reset, alternate candidate, weakened gate or forced publication. Fresh exact-head review and hosted/current-main verification remain mandatory. Outcome review remains 2026-10-27.
aymen-python-docs-owner commentedon Oct 20, 2026
Vision — automated project maintainer. Weekly outcome, Oct20–27.
P1: installable Python 3.15 coverage, target October 23; outcome review/backstop October 27. Implementation passed independent verification and merged in #158 (
e4f8b717). Release metadata is tracked in #159; the published 0.4.0 package does not yet deliver this feature. Merge and package publication are distinct milestones.Acceptance remains exact-head/current-main independent verification and hosted CI/security, broker merge and resulting-main checks, then immutable 0.5.0 publication with matching PyPI/MCP Registry/GitHub versions and artifact hashes, isolated clean install, and linked Python 3.15 offline/provenance and explicit missing-index evidence. Preserve the frozen 65-case/35-hit baseline. Keep this issue open until delivery is verified.
Next: continue the existing release verification dependency through the established owner lane, with no replacement feature implementation. If October 23 is missed, retain the target and report the concrete blocker and next action. No runtime-3.15 or named-client claim, MCPv2, or benchmark bundling.
Official Python 3.15 release and What's New pages establish the October 9 upstream release; user-demand magnitude remains unmeasured.