LearnNewsExamplesServices
Frontmatter
id12729
titleClarify v13 upgrade path in release notes
stateClosed
labels
documentationenhancementai
assigneesneo-gpt
createdAtJun 8, 2026, 5:45 AM
updatedAtJun 8, 2026, 10:54 AM
githubUrlhttps://github.com/neomjs/neo/issues/12729
authorneo-gpt
commentsCount0
parentIssue12696
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtJun 8, 2026, 10:54 AM

Clarify v13 upgrade path in release notes

Closed v13.0.0/archive-v13-0-0-chunk-17 documentationenhancementai
neo-gpt
neo-gpt commented on Jun 8, 2026, 5:45 AM

Problem Scope

The v13 release notes currently have a single conceptual Upgrade Path line:

Existing Body/runtime work continues; v13 makes the Brain that builds and maintains it operational at release scale.

That sentence is directionally true, but it does not meet the established release-note bar from resources/content/release-notes/chunk-2/v12.1.0.md and resources/content/release-notes/chunk-2/v11.24.0.md, where the Upgrade Path line answers the reader's compatibility question directly.

For v13, the release artifact needs an actionable upgrade / migration note that distinguishes:

  • Body/runtime app compatibility expectations.
  • Agent OS / operator-surface changes that are new in v13.
  • Known release-line boundaries that must not be implied as already shipped.

This is a release-blocking leaf under #12696, already identified in the epic comments as: "Migration / upgrade-path note — v12.1→v13 (v12.x notes carry an Upgrade Path line; confirm drop-in vs breaking)."

Evidence

  • resources/content/release-notes/v13.0.0.md currently has only the conceptual line above.
  • resources/content/release-notes/chunk-2/v12.1.0.md says Drop-in replacement for v12.0.0.
  • resources/content/release-notes/chunk-2/v11.24.0.md says Drop-in replacement for v11.23.0.
  • Live duplicate sweep returned no open GitHub issue for v13 upgrade path release notes or v13 migration note.
  • Local content sweep found no existing dedicated v13 release-note migration leaf; it found only the current v13 line and older release-note precedent lines.
  • KB ticket sweep did not identify a relevant duplicate.

Intended Solution Shape

Update resources/content/release-notes/v13.0.0.md with a concise but explicit Upgrade / Migration Notes section that answers what changes for existing Neo consumers and what changes for Neo operators/maintainers.

The section should preserve the v13 thesis without overselling unfinished work:

  • Body/runtime work continues; do not frame v13 as abandoning the application engine.
  • Agent OS surfaces are the new operational substrate; name this as an operational upgrade, not as a required app migration.
  • Body/Grid wording must respect the #9492 design-lock cut-line and must not claim #9872 landed.
  • Release-cut metadata such as isDraft, publishedAt, version publish mechanics, and human-only release-line mutation stay out of this leaf.

Acceptance Criteria

  • resources/content/release-notes/v13.0.0.md contains an explicit v13 Upgrade / Migration Notes section or strengthened Upgrade Path block.
  • The wording directly answers compatibility / migration expectations for existing Body/runtime users.
  • The wording separately calls out Agent OS / operator-surface changes as v13's major new operational layer.
  • The note does not claim unfinished Body/Grid orchestration work as shipped.
  • The note does not duplicate #12723 appendix-count work, #12727 SEO work, or release-cut metadata work.
  • The PR body compares the result against the v12.1 / v11.24 Upgrade Path precedent.

Out Of Scope

  • Final isDraft / publishedAt release metadata.
  • Version bump or buildScripts/release/publish.mjs release-line execution.
  • Regenerating appendix counts already covered by #12723.
  • Restoring SEO route coverage already covered by #12727.
  • Authoring the future release-notes skill (#10321).
  • Implementing Body/Grid wrapper selection-model code.

Avoided Traps

  • Conceptual thesis instead of migration answer: the current sentence is true but too abstract for a major release.
  • Framework-abandonment framing: v13's Brain/Agent OS lands on top of the Body; it is not a pivot away from runtime/application-engine work.
  • Premature release-cut claims: this leaf improves the release-note contract without flipping draft state or implying human-only release steps happened.

Authored by GPT-5 Codex (Codex Desktop).

tobiu referenced in commit b43c238 - "docs(release): clarify v13 upgrade path (#12729) (#12730)" on Jun 8, 2026, 10:54 AM
tobiu closed this issue on Jun 8, 2026, 10:54 AM