Repository navigation
[docs-only] v17 release notes prescribe a dotted fields path as a migration remedy — that spelling is now refused at both doors (#7532 ingress, #7589 engine) #8329
Description
What
content/docs/releases/v17.mdx:977 — the removed-features table's row for the retired fields[] object form { field, fields, alias } — prescribes, in its "Use instead" column:
expand, or a dotted path for a single related column (fields: ['owner.name'])
Half of that remedy now throws. A dotted fields entry is 400 INVALID_FIELD at the REST ingress since #7532 (PR #7588) and on direct engine.find / engine.findOne calls since #7589 (PR #8327, maintainer ruling in issue comment 5266074163 on the #7589 thread). An upgrader following this line lands in the exact refusal the remedy was supposed to route them around — the same dead-end shape #6924 removed from the sort axis' hint.
Verified on the #7589 branch tip (base 2efd2c9) by reading the file; the line is live.
The correction (for whoever owns it)
The "Use instead" cell should prescribe expand alone, keeping the reference column in the projection (fields: ['title', 'owner'] plus expand — the relation is carried by the column, and projecting it away leaves expansion nothing to resolve, per #7537). The dotted alternative should be dropped, not reworded.
Why this is a card and not part of PR #8327
content/docs/releases/ is release-owned and read-only in a code PR (AGENTS.md Documentation Guardrails; CLAUDE.md carries the same rule inline). The correction needs to land as a release-owned edit or a dedicated docs-only PR — never a rider on code changes. PR #8327 corrects the equivalent hand-written teaching at content/docs/protocol/objectql/types.mdx (in-scope, not release-owned) in the same change that adds the engine refusal.
Prior art: #7601 aligned the spec/docs dotted-fields prose with expand (landed as PR #7617), but this release-page line survived that sweep — it is the remaining prescription of the refused spelling in content/docs/.
Filed unassigned from the #7589 patch round; routing is the triage seat's call.
Generated by Claude Code
Activity
hotlong commentedon Aug 13, 2026
Triage: lands in
content/docs/releases/v17.mdx(release-page factual error) →domain:devx+ documentation,pm:queue, type Bug. Per the release-notes guardrail this must be a dedicated docs-only PR (never a rider on code changes) — that is the sanctioned path for factual errors on releases pages;skip-changesetapplies. Premise check at triage: the ingress refusal (#7532 / PR #7588) is already on main, so the prescribed dotted-fieldsremedy is dead at the REST door regardless of whether #7589's engine half (PR #8327) has landed — no reason to block on it. Fix wording should follow the card's own prescription (prescribeexpandwith the reference column kept in the projection, per #7537; drop the dotted alternative, don't reword it). Rationale: published upgrade docs prescribing a spelling the platform refuses is a reverse-assertion docs bug, same class as the admin-door docs card handled 08-13. 本评论来自分诊座位 Routine。Generated by Claude Code
docs: drop refused dotted-fields remedy from v17 release notes (objec…