docs(releases): draft the 17.5.0 release notes and upgrade checklist - #20396
Merged
Merged
Conversation
Compile content/docs/releases/v17/17-5.mdx from the 868 changesets pending on main at ab6fb02 (every changeset read in full, triaged into breaking / new / fix / internal), cross-checked against the 18 ADR-0087 conversions registered under protocol major 18 since 17.4.0. Register the page in the v17 meta.json. The page is a pre-cut draft: an MDX comment at its top lists the four release-time edits (publish date, late changesets, CHANGELOG entry count, v17/index.mdx status blockquote). v17/index.mdx is deliberately untouched so the page claims nothing about a release that has not happened. Claude-Session: https://claude.ai/code/session_014VGCS11YUtYAiinRcdqQwL Co-authored-by: Claude <noreply@anthropic.com>
github-actions
Bot
added
size/xl
documentation
hotlong
added
the
skip-changeset
Claude
Fix the four Lint & Repo Gates findings on the 17.5.0 page: - check:doc-anchors: an in-list ```ts fence had been collapsed onto one line, so the gate read everything after it as fenced and found none of the later headings. Restore the multi-line fence. - check:issue-citations: 26 PR numbers taken from squash-commit subjects answer 404 on the board. Cite the resolvable commit sha instead; no replacement number is guessed. - check:role-word: reword the two occurrences of the reserved word. - check:docs-audit-scope: list the new page in handwritten-docs.json (regenerated with check-audit-scope.mjs --write, +1 row). Also reflow the prose lines those edits left over-long. Claude-Session: https://claude.ai/code/session_014VGCS11YUtYAiinRcdqQwL Co-authored-by: Claude <noreply@anthropic.com>
Contributor
📓 Docs Drift CheckNothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs. What this run could not see
Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): |
hotlong
marked this pull request as ready for review
September 28, 2026 10:23
hotlong
enabled auto-merge
September 28, 2026 10:24
veigajoao
pushed a commit
to veigajoao/objectstack
that referenced
this pull request
Sep 29, 2026
…ai#20623) ## What this is The release-time half of the 17.5.0 release notes. The page `content/docs/releases/v17/17-5.mdx` landed before the cut (objectstack-ai#20396) with a `RELEASE-TIME TODO` comment listing four edits to make once 17.5.0 was on npm. 17.5.0 was published on 2026-09-29 (`@objectstack/cli@17.5.0` at 07:58Z, the last package, `@objectstack/spec`, at 08:09Z). This PR makes those edits, deletes both TODO comments, and updates `content/docs/releases/v17/index.mdx`. Docs-only: two files under `content/docs/releases/`, which is release-owned, so this is the dedicated docs-only PR `AGENTS.md` sanctions for that tree. It publishes nothing from any package, hence `skip-changeset`. ## What changed **`17-5.mdx`** - **Publish date.** "What's new" now opens: 17.5.0 was published to the `latest` tag on 2026-09-29, 20 days after 17.4.0. - **Count.** The draft said it was compiled from "868 changesets pending on `main` at `ab6fb027`". The version commit `8c87d26a` (objectstack-ai#17076) actually consumed **958** changesets (the `.changeset/*.md` files it deletes, README excluded). The page now states 958 as its measure and cross-checks it against the CHANGELOGs: the 69 package `CHANGELOG.md` files that carry a 17.5.0 section at `8c87d26a` list **1,372 per-package entries** (703 minor, 669 patch, 0 major) in 56 of those files, and those entries de-duplicate to exactly the same 958. - **The 90 changesets the draft never read**, the ones consumed by `8c87d26a` but not pending at `ab6fb027`, were each read in full and folded in: - **Breaking changes & migration: 45.** Two new subsections: *Written values are held to the field's declared type* (date and datetime ISO spellings on a real day, the year range 0001–9999, the numeric string grammar, `precision`, `progress` bounds, `/import` thousands commas, with a Migration table) and *An edge-branched decision takes its first matching branch* (objectstack-ai#20344, with the stored-row caveat). The rest joined existing subsections: RLS cross-class comparisons; org-less grants; cube `public`; number comparands, `having` placeholders and double accumulation; flow node config, `connector_action`, `api` flow secrets and the connector resilience keys; list-view `tabs`, action `aria` and view round-trip keys; `/diff` `/history` `/audit` as authoring doors and OpenAPI `info`; remote Turso and unbuildable indexes; the one stack authoring shape and new lint positions; QA `requires`, narrowed published types and `retiredAfter`. - **New capabilities: 11.** Studio form rows for 27 structured keys, the staged `$empty` operator, the new `ComponentPropsMap` rows, and email verification under `open`. - **Notable fixes: 15.** Dispatcher-only hosts, `/diff` default range, plain-text email faces, auth-settings sibling isolation, SQLite `reclaimSpace()`, zh-CN/ja-JP/es-ES object labels, aggregate `search`, and the OSV sweep. - **New in Console: 2.** The fourth objectui pin move and the `trash-2` → `trash` icon. - **Judged too minor to surface: 17.** Each is text only, with no behaviour change an app or operator can reach: describe, docblock and comment rewrites, `os migrate meta` guidance text, liveness-ledger data and layout, a form row's declared language, a test-only import change in `plugin-dev`, and the successor `Link` header of the deprecated `?layers=true` flag on the environment-scoped mount. - **Highlights** gain three bullets drawn from the above (decision first-match, written values, the stack authoring shape). The "running deployment" warning list gains five lines. - Every breaking entry that needs an operator action has an upgrade-checklist line, marked *Not exercised* unless the HotCRM upgrade below exercised it. - **Console.** Four pin moves now, not three: `f8a9d0fb0596 → dd3f7e1be356` (`3cf6449`, objectstack-ai#20436) carries 325 releasing objectui changesets, 41 of them declared breaking upstream. The Highlights, "What's new" and Console sections all say four. - **Dependencies.** `nodemailer` is `^10.0.2`, not `^9.1.1`. That is a major bump for GHSA-6vj9-mwq6-2f5v, which has no 9.x fix. The line also carries the operator-visible note from objectstack-ai#20564's changeset: from nodemailer 10.0.12, `requireTLS` wins over `ignoreTLS`, so a `transportOptions: { ignoreTLS: true }` override on a port other than 465 now upgrades to STARTTLS or fails the send, and `secure: false` is the way to connect in the clear. - **New subsection "Also shipped in 17.5.0 — not in its CHANGELOG".** The publish ran from `main` at `0f6dcac5` (Release run 36536081716), 8 first-parent commits after the version commit, so the npm packages also contain `6e3aa75e a093ce3 92fe081 3a89d45 7001918 c96beb2 ba4648d 0f6dcac`. Their changesets are still unconsumed in `.changeset/`. The subsection gives one line per commit and says they will be listed again in 17.6.0's CHANGELOG and that the cause is tracked in objectstack-ai#20613. The breaking `92fe0814` (objectstack-ai#20458, cube member inner `name` retired) gets a Migration note taken from its own changeset and a checklist entry, and the checklist preface says where that note lives. **`v17/index.mdx`** (following the 17.4.0 curation precedent `b11bfb9a`) - frontmatter description: "17.0.0 through 17.5.0"; - status blockquote: 17.5.0 is released and current, published 2026-09-29, taking over from 17.4.0; a plain install resolves 17.5.0; the minors warning names 17.5.0; - a "17.5.0 stays in that register" paragraph drawn from the page's Highlights, linking `#breaking-changes--migration-in-1750` and `#upgrade-checklist`; - the per-release list marks 17.5.0 current and 17.4.0 no longer current; - the checklist callout records that 17.4.0 → 17.5.0 has been exercised only in part (seven lines, on HotCRM), and the per-release checklist links lead with 17.5.0. ## Findings from a HotCRM 17.4.0 → 17.5.0 upgrade These were folded in at the coordinator's request; the parent session verified them. - **Decision-mode flip** (objectstack-ai#20344): now a 17.4.0 → 17.5.0 table, a standing warning that flows stored in `sys_metadata` take the new meaning without being rewritten, and a checklist line. The line says to review each `mode: 'inclusive'` that `os migrate meta --from 17` offers, deleting it where the conditions partition, because applied blindly it draws `flow-decision-inclusive-overlap`. It then says to review the `--stored` list. - **`specVersion` / `engines.protocol`**: the checklist now says what an app does after a 17.x minor, from the code. `PROTOCOL_VERSION` is still `17.0.0`, and the handshake compares only the major, so `engines.protocol: '^17'` stays, a `^17.0.0` `specVersion` admits 17.5.0, and a `^18` range is refused `OS_PROTOCOL_INCOMPATIBLE`. "Protocol 18" is the migration registry's next major; the 17.5.0 schemas already refuse its shapes, which is why `os migrate meta --from 17` runs to 18. The Breaking-changes intro carries the same sentence. - **Seven checklist lines** are marked *Exercised on HotCRM (a 17.4.0 app with a 17.4.0-created SQLite DB), 2026-09-29* with the observed result: `os doctor` scheduled-work reading, the `account-issuer` pre-flight, `os migrate meta --from 17` (41 refusals in 874 lines, 240 of them generic protocol-18 notices, so filter the output), the decision review with `--stored` (0 rows), `page.assignedProfiles`, lookup screen field `reference`, and `chartConfig` (34 sites). Every other line stays *Not exercised*, and the preface and the v17 index callout say the hop was exercised only in part. ## Citations Every added `#N` was resolved on the board: 144 candidate numbers from the 90 commits and the 8 post-version commits, all resolving, and objectstack-ai#20613 is open. SHAs are 7-character short SHAs, and each was verified to resolve unambiguously. ## Gates run (workspace installed) The full sweep ran on `2b3b323b`. The head `664854a4` changes one phrase in one checklist line, and on it the MDX parse, `check:doc-anchors`, `check:role-word`, `check:issue-citations --base origin/main`, the audit-scope gate and the release-page gates were re-run, all green. Named in the task, all exit 0: - `pnpm check:doc-anchors`: 391 internal fragment links, all resolve. - `node scripts/check-issue-citations.mjs --base origin/main`: 119 citations judged (104 resolve as pull requests, 1 as an issue, 14 cross-repo `objectui#N` unjudged); every added citation resolves. - `pnpm check:role-word`: no new occurrences. - `node scripts/docs-audit/check-audit-scope.mjs`: in sync, and release-owned pages are review-only. - `check-release-page-status`, `check-release-section-coverage` (plain and `--strict`) and `check-release-notes`: all OK. - MDX parse: both pages compile with `@mdx-js/mdx` 3 + `remark-gfm`, and all 7 tables on `17-5.mdx` parse with no ragged rows. Derived with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands`: 47 commands, **all 47 exit 0**. The first sweep hit 5 prerequisite refusals (exit 3, or `check:docs` on the missing gitignored `json-schema` tree) from unbuilt `@objectstack/spec`, `@objectstack/formula`, `@objectstack/lint` and `@objectstack/client-react`. None was a finding. Those packages were built and the whole list was re-run. Among the 47: `check:doc-authoring`, `check:docs-single-h1`, `check:docs-redirects`, `check:corpus-claim-drift`, `check:docs-transcript-drift`, `@objectstack/spec check:docs` / `check:skill-examples` / `check:liveness`, `@objectstack/lint check:doc-formula-expressions` / `check:doc-security-posture`, `check-doc-frontmatter`, `check-docs-section-name`, `check-section-landing-index` and `check:nul-bytes`. The diff was also re-read by hand; the fixes from that pass are the second commit (`da443bdb`). ## Not in this PR `content/docs/upgrading.mdx`'s per-release table still reads "v17.4.0 — ⛔ checklist not written; machine-draft notes only" and has no 17.5.0 row. It is a hand-written tree outside `content/docs/releases/`, so it is left for a separate change. --- _Generated by [Claude Code](https://claude.ai/code/session_014VGCS11YUtYAiinRcdqQwL)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
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
2 participants
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.
What this is
A pre-cut draft of the curated release page for 17.5.0,
content/docs/releases/v17/17-5.mdx, plus its entry incontent/docs/releases/v17/meta.jsonand inscripts/docs-audit/handwritten-docs.json. Docs-only; no code, no changeset (skip-changeset: the page is the release-time compilation of the changesets, perdocs/releases-maintenance.md§3, and publishes nothing from any package).It follows the 17.4.0 page's structure: Highlights → What's new → Breaking changes & migration (triaged, not exhaustive) → New capabilities → Notable fixes → New in Console (Studio) → Upgrade checklist (every line marked not exercised).
How it was compiled
mainatab6fb027(866 at15bf186fplus two text-onlypatchentries landed since). Every changeset was read in full and triaged into breaking / new / fix / internal, with PR numbers and short SHAs taken from the commit that added each changeset.check:issue-citations, allocated-but-absent). The page cites the resolvable commit SHA for those instead and guesses no replacement number. (The second commit's message says 26; 28 is the correct count — 3 fixed by hand, 25 by script.)packages/spec/src/conversions/registry.tssince the 17.4.0 version commit (7e633700), all registered under protocol major 18, are each covered by a migration entry on the page.53ded82bf7a4 → 87af769e9a3e → 62597c588072 → f8a9d0fb0596). The first bump's changeset lists only 100 of its 584 releasing objectui entries, and the page says so.translation-target-unknownbecomes anerrorin 17.5.0 (the 17.4.0 lint CHANGELOG carries no such change, despite one changeset saying "since 17.4.0"); and the organizationmetadatachange (fix(plugin-auth,spec,client): the identity read routes serve what the spec declares #19122) is listed as a wire-type change even though its changeset declares a widening.Deliberately not in this PR
content/docs/releases/v17/index.mdxis untouched. Its release-status blockquote and per-release list must only claim 17.5.0 after it ships, so that edit belongs at release time.17-5.mdxlists the four release-time edits: publish date, changesets landed afterab6fb027, the per-package CHANGELOG entry count, and thev17/index.mdxupdate.Landing: the maintainer decided (2026-09-28) to land this page before the 17.5.0 cut. The four release-time edits above follow in a separate docs-only PR once 17.5.0 is on npm; until then the docs site shows the 17.5.0 page ahead of the release.
Verification
Run locally on the head commit, with the workspace installed:
check:doc-anchors,check:issue-citations,check:role-word,check:docs-audit-scope— the four gates the first push failed or would have failed — now pass.check:nul-bytes,check:doc-authoring,check-doc-frontmatter,check-docs-nav-label,check:docs-single-h1,check:docs-redirects,check:docs-locale-catch-all,check-doc-route-spelling --advisory,check-docs-section-name,check:published-readme-links,check:docs-image-tag,check:corpus-claim-drift,check-section-landing-index,check:release-notes,check:release-page-status,check-release-section-coverage(plain and--strict),check:release-body,check-scripts-symbol-anchors.@mdx-js/mdx3 +remark-gfm, and all four tables parse with no ragged rows. On the head commit every CI check is green,Lint & Repo GatesandBuild Docsincluded.Generated by Claude Code