Skip to content

Document in-place upgrades - #712

Merged
SaladDay merged 1 commit into
mainfrom
document-in-place-upgrades
Oct 15, 2026
Merged

SaladDay merged 1 commit into
mainfrom
document-in-place-upgrades

Conversation

@SaladDay

@SaladDay SaladDay commented Oct 15, 2026 •

Copy link
Copy Markdown
Collaborator

What

Documents the in-place upgrade that init (#711) and the installers (#710) now implement, and removes the "one release for life" claims.

  • docs/getting-started/operations.md: Upgrade (#upgrade) replaces the installation version policy and moves before Uninstall. It covers what is kept, the v0.0.10+ support boundary, the required backup, the command (published install.sh/install.ps1 --upgrade, install.py --upgrade for source bundles), refusal without the flag, what the upgrade does and its failure and recovery points, applying the Runtime afterward, protocol changes and their operator actions, the downgrade refusals from init and Core (quoted verbatim), and rollback. The oac apply row links to How oac apply works. The Back up note now says to restore the volume together with its installation directory. Troubleshooting: three rows quoted messages the installer no longer prints, so they now quote the real strings. Two rows are new: data volume check failed and This installation runs release ….
  • install.md, install-options.md: rerun and standalone Compose/Dokploy/Coolify text points to Upgrade. A standalone Compose upgrade deploys the new compose.yaml with the same project, environment and volume. Installation actions gains a --upgrade row.
  • nodes.md: Node software replaces One release: nodes keep their host program across a Core upgrade, and protocol changes link to the actions. The rerun bullet no longer overclaims. A rerun after a sandbox configuration change is refused with Retained node specification differs from Core (deploy/node/node_spec.py:153-158, allow_selection_change=False from configure_node).
  • development.md: install.py resumes its own release and upgrades with --upgrade. The "delete everything for a new commit" procedure is removed.
  • configuration.md layout: drops compose-sha256sums.txt. Adds a compose.override.yaml row, because a source-bundle upgrade rewrites only its own entries and requires the file to stay JSON (deploy/install-source.py). This is the only place that requirement is documented.
  • maintainers.md: one release-checklist line. Core must never require a secret or file that only a newer init creates, because an upgrade runs the new Core's check-config before the new init.
  • contracts/agents-api/node-generation-protocol.md: drops "The current wire version is 5". Line 9 already binds frames to node.ProtocolVersion (now 6), so the number had a second home that went stale.
  • AGENTS.md: names the upgrade contract the pre-release paragraph anticipates. CONTRIBUTING.md: owner links point to #upgrade. services/core/README.md: Core refuses a newer schema.
  • Web: the update_required help tip (Node software incompatible) now matches its producer. That producer is deployment/health.go:82: an online node without generation management that enrolled at an older target (sandbox-deployment.md:145). The tip says the node can't prepare new configurations, and to choose Remove node and add the host again with Add node. Updated in en (key) and zh-CN.
  • zh mirrors for every docs/ and contracts/agents-api/ file, with source_hash refreshed.

Why

In-place upgrades are supported from v0.0.10. The operator docs, contributor rules and one console tip still said a new release needs a new installation.

Verification

  • node --test website/tests/translations.test.mjs: 3/3 pass (website dependencies installed locally, so test 3 ran too)
  • make check-names check-docs check-ci: pass
  • pnpm --filter @oac/web typecheck: pass
  • pnpm --filter @oac/web exec vitest run src/i18n/i18n.test.tsx src/features/sandbox/SandboxRolloutSummary.test.tsx src/features/sandbox/NodeList.test.ts: 19/19 pass
  • grep -rn installation-version-policy: no matches

Skipped

  • Go tests and go vet: no Go change.
  • Browser tests and screenshots: no layout change, only one help-tip string.
  • Full make check: not needed for this change.

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.

@SaladDay
SaladDay merged commit c222381 into main Oct 15, 2026
17 checks passed
@SaladDay
SaladDay deleted the document-in-place-upgrades branch October 15, 2026 07:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant