Docs: dev-setup instructions leave a contributor with no test runner, and CHANGELOG is missing four merged PRs - #236
Docs: dev-setup instructions leave a contributor with no test runner, and CHANGELOG is missing four merged PRs#236jaylfc wants to merge 1 commit into
Conversation
…#215, #219 README.md now has an explicit Dev setup section with the working uv commands (uv sync, uv run pytest). The old pip install -e . instructions are kept for runtime use, with a plain warning that they give you no test runner. pip is not documented as a dev path because it is not available in this environment and PEP 735 --group support could not be verified. CHANGELOG.md Unreleased gains short entries for A2A envelope refs+blocks (#212), GET /version capabilities (#213), CollectionStore _db.connect helper (#215), and the PEP 735 dev dependency group (#219). Fixes the two doc-staleness problems found in the 2026-07-28 audit.
|
ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing |
📝 WalkthroughWalkthroughThe pull request updates the changelog and README. The documentation covers recent API and dependency changes and defines a ChangesDocumentation updates
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
|
|
||
| Dev and test dependencies moved into a PEP 735 `[dependency-groups] dev` group, so a bare `uv sync` from a clean checkout installs pytest, pytest-asyncio, and the auth extras needed by the test suite with no flags (PR #219). | ||
|
|
||
| `GET /version` with a capability list (new `taosmd.capabilities` module). The server now publishes what the running build actually supports, because neither a status code nor a version number could answer that. `taosmd serve` renders the dashboard SPA on unknown non-API paths, so `GET /collections` returns `200 text/html` on a build with no collections code, and an integrator who "verified" a route by checking for a 200 got a confident yes from a server that could not do the thing (this really happened, against the wrong service). Semver does not close the gap either: features land continuously between bumps, and a production box sat a month stale without anyone noticing even though `GET /health` already reported a version. `/version` returns `{"version", "commit", "commit_source", "built_at", "built_at_source", "capabilities"}` and `GET /health` gains the same `capabilities` list alongside its existing `status` and `version` keys, which are unchanged (taOS and the dashboard consume both). Both endpoints are unauthenticated by design, joining `/health` in `_PUBLIC_PATHS`, so monitoring and drift probes keep working on a token-secured box; they expose build identity and capability identifiers only (no paths, no tokens, no configuration). Capabilities are **stable contract identifiers with an explicit version suffix** (`collections.v1`, `grants.v1`, `temporal.v1`, `a2a.v1`, `tasks.v1`, `ingest.v1`, `search.v1`, `graph.v1`, `shelves.v1`), not feature names: a breaking change to a wire contract becomes `collections.v2`, so a client pinned to `collections.v1` sees the capability disappear (a visible break it can act on) rather than `collections` silently meaning something new; additive changes keep the identifier. The list is derived at request time by probing the running build (each identifier is declared next to the module and symbols that implement it, and is advertised only if they resolve), so deleting or renaming an implementation deletes the claim instead of leaving a stale boast, and a divergence test asserts every declared capability's routes exist in the real dispatcher. The commit sha is resolved once at first call and cached, never per request and never by shelling out: `git rev-parse` in a request path can block on a lock or a slow filesystem, so the git plumbing is read directly from the filesystem (`.git/HEAD` -> loose ref or `packed-refs`, including the `gitdir:` indirection used by worktrees and submodules), with an optional packaged `taosmd/_build_info.py` stamp taking precedence for wheel and container builds. Every step degrades to `null` rather than raising, so a pip install with no checkout and no stamp still gets a working endpoint. |
There was a problem hiding this comment.
WARNING: Duplicate CHANGELOG entry for PR #213
The new concise entry at line 7 (GET /version endpoint with a contract-identifier capabilities list) describes the same change as the existing verbose entry starting at this line (GET /version with a capability list). Both reference PR #213.
The old entry should have been removed when the new concise entries were inserted. As written, the Unreleased section contains two different versions of the same release note, which will produce duplicate or conflicting entries when the changelog is cut.
Reply with @kilocode-bot fix it to have Kilo Code address this issue.
Code Review SummaryStatus: 1 Issue Found | Recommendation: Address before merge Overview
Issue Details (click to expand)WARNING
Files Reviewed (2 files)
Fix these issues in Kilo Cloud Reviewed by step-3.7-flash · Input: 63K · Output: 5K · Cached: 401.3K |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CHANGELOG.md`:
- Line 7: Remove the duplicate /version capabilities release note from
CHANGELOG.md, preserving a single canonical entry and merging any unique useful
details into it before deleting the repetition.
In `@README.md`:
- Line 65: Update the editable-install warning in the README’s Install paragraph
to accurately state that pip install -e . succeeds but does not install the PEP
735 dev dependency group, test dependencies, or a test runner; remove the claim
that the failure is silent.
- Around line 118-120: Update the README setup documentation to remove the
temporary explanation about pip availability, the current environment, and
unverified PEP 735 support. State only the stable supported setup contract,
identifying uv sync as the supported short path.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 53dab621-8e46-47d2-91c8-376e454bd526
📒 Files selected for processing (2)
CHANGELOG.mdREADME.md
|
|
||
| A2A message envelope: `POST /a2a/send` now accepts optional `refs` and `blocks` fields. `refs` is a list of up to 8 structured reference objects (kind, title, uri, etc.), and `blocks` is a list of arbitrary objects for rich content. The total serialized message is capped at 64KB. `body` remains required when `blocks` is absent, and is required alongside `blocks` when blocks are present (PR #212). | ||
|
|
||
| `GET /version` endpoint with a contract-identifier capabilities list (new `taosmd.capabilities` module). The server publishes what the running build actually supports, because neither a status code nor a version number could answer that question reliably. `GET /health` also gains the same capabilities list. Capabilities are stable contract identifiers with an explicit version suffix (e.g. `collections.v1`), not feature names, so a breaking change becomes `collections.v2` and a client pinned to `v1` sees the capability disappear rather than silently meaning something new. The list is derived at request time by probing the running build (PR #213). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove the duplicate /version release note.
This entry repeats the /version and capabilities change already documented in Line [13] of CHANGELOG.md. Keep one canonical entry, or merge the additional detail into this entry and remove the duplicate.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CHANGELOG.md` at line 7, Remove the duplicate /version capabilities release
note from CHANGELOG.md, preserving a single canonical entry and merging any
unique useful details into it before deleting the repetition.
| ### One-Line Setup (manual) | ||
|
|
||
| > **Install:** `pip install taosmd` (add the MCP server with `pip install "taosmd[mcp]"`). For a source/dev install instead, `git clone` then `pip install -e .`. The one-line bootstrap below additionally installs Ollama and downloads the embedding and LLM models; it is newer and still being validated across clean machines, so please report issues. | ||
| > **Install:** `pip install taosmd` (add the MCP server with `pip install "taosmd[mcp]"`). For a source install instead, `git clone` then `pip install -e .`. Warning: `pip install -e .` installs the runtime only and gives you no test runner. The failure is silent, so a reader will otherwise assume their setup worked. See the Dev setup section below for the working commands. The one-line bootstrap below additionally installs Ollama and downloads the embedding and LLM models; it is newer and still being validated across clean machines, so please report issues. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Confirm the dependency-group configuration and the related README wording.
rg -n -A12 -B2 '^\[dependency-groups\]' pyproject.toml
rg -n -C2 'The failure is silent|pip install -e \.|uv sync' README.mdRepository: jaylfc/taosmd
Length of output: 2173
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== editable install installable metadata =="
sed -n '1,140p' pyproject.toml
echo
echo "== references to dependency groups / optional extras =="
rg -n 'dependency-groups|group=|optional-dependencies|uv (install|sync)|pip install \.|-e|pytest|test runner' README.md pyproject.toml
echo
echo "== package files =="
git ls-files | sed -n '/pyproject.toml/,+100p' | head -80Repository: jaylfc/taosmd
Length of output: 19083
Describe the editable install result accurately.
pip install -e . installs the package successfully, but it does not install the PEP 735 dev dependency group or test tooling. Replace “The failure is silent” with wording such as “The install succeeds, but it does not install the test dependencies or a test runner.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` at line 65, Update the editable-install warning in the README’s
Install paragraph to accurately state that pip install -e . succeeds but does
not install the PEP 735 dev dependency group, test dependencies, or a test
runner; remove the claim that the failure is silent.
| `pip` is not documented as a working dev-setup path here because it is not | ||
| available in this environment and PEP 735 `--group` support could not be | ||
| verified. `uv sync` is the supported short path. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Confirm that the supported README path matches the repository configuration.
rg -n -A12 -B2 '^\[dependency-groups\]' pyproject.toml
rg -n -C3 'not available in this environment|PEP 735|uv sync' README.mdRepository: jaylfc/taosmd
Length of output: 1281
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the dependency configuration and README dev-setup section around the reported lines.
cat -n pyproject.toml | sed -n '1,70p'
printf '\n--- README dev-setup section ---\n'
cat -n README.md | sed -n '96,128p'Repository: jaylfc/taosmd
Length of output: 4020
Remove the temporary environment explanation from the public docs.
“This environment” describes a local verification limitation, not a stable project requirement. State the supported contract directly. For example:
Suggested wording
-`pip` is not documented as a working dev-setup path here because it is not
-available in this environment and PEP 735 `--group` support could not be
-verified. `uv sync` is the supported short path.
+`uv sync` is the supported development-install path. It installs the project
+and its development dependency group.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| `pip` is not documented as a working dev-setup path here because it is not | |
| available in this environment and PEP 735 `--group` support could not be | |
| verified. `uv sync` is the supported short path. | |
| `uv sync` is the supported development-install path. It installs the project | |
| and its development dependency group. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 118 - 120, Update the README setup documentation to
remove the temporary explanation about pip availability, the current
environment, and unverified PEP 735 support. State only the stable supported
setup contract, identifying uv sync as the supported short path.
|
Reviewed. Apologies for the delay: this has been open since 9 August with every check green and no comment from me. I found it by enumerating the open PRs rather than trusting my own notes, which had it listed nowhere. The README half is a real gap correctly filled. One blocker in the CHANGELOG half, and one sentence to cut. BLOCKER: the CHANGELOG now describes
|
|
One more CHANGELOG item for this PR while you are in that section, so it does not need a second pass. #240 (deleted-symbols gate, merged today as f6b5a17) has no CHANGELOG entry. I checked master: zero mentions of the gate. It belongs in I deliberately did not commit it straight to master, because this PR is already editing that exact section and a master commit would hand you a conflict for no reason. The part worth writing down is the waiver, which is currently undiscoverable: a Making the failure message itself say so is carded separately as tsk-gkmvcp and is not your job here. A CHANGELOG line is. |
|
Revision card filed: Filed late, and the reason is worth recording rather than glossing. When I enumerated the frozen PR set earlier I built the list from my own running notes instead of from a fresh sweep of open PRs against "has unresolved review findings", so this PR was missed while eight others got cards. The hourly freshness pass caught it. That is the same failure I have written up twice today: an accurate local observation generalised into a list I never re-measured. Mechanics as with the others: |
|
Closing as superseded by #256. The review of this PR asked for the revision; Verified before closing: #256 branches off This PR was holding one of the 8 CI throttle slots on |
1 participant
CARD TITLE (intent, not commit subject): Docs: dev-setup instructions leave a contributor with no test runner, and CHANGELOG is missing four merged PRs
Autonomous build of board card tsk-twljv4.
README.md now has an explicit Dev setup section with the working uv
commands (uv sync, uv run pytest). The old pip install -e . instructions
are kept for runtime use, with a plain warning that they give you no test
runner. pip is not documented as a dev path because it is not available
in this environment and PEP 735 --group support could not be verified.
CHANGELOG.md Unreleased gains short entries for A2A envelope refs+blocks
(#212), GET /version capabilities (#213), CollectionStore _db.connect
helper (#215), and the PEP 735 dev dependency group (#219).
Fixes the two doc-staleness problems found in the 2026-07-28 audit.
Files:
CHANGELOG.md | 8 ++++++++
README.md | 24 +++++++++++++++++++++++-
2 files changed, 31 insertions(+), 1 deletion(-)
Summary by CodeRabbit
New Features
/versionendpoint and included the same information in/health.Documentation
uv-based development setup and verification steps.pipis not the recommended development installation path.