Skip to content

upgrading.mdx

Latest commit

 

History

History
355 lines (288 loc) · 17.3 KB

upgrading.mdx

File metadata and controls

355 lines (288 loc) · 17.3 KB
Raw
title Upgrading
description ObjectStack upgrades come in two halves that run on separate clocks — the platform runtime and your metadata app. Which one you are doing, what each one moves, and where the per-major checklists live.

There are two upgrades on this platform, and they run on separate clocks:

Platform runtime Metadata app
Ships as a Docker image (or the os CLI on a host) a compiled artifact, dist/objectstack.json
Versioned by our release train (X.Y.Z) your own catalog
Whose cadence ours yours
The upgrade action move the image tag, or the dependency pins, then restart os migrate meta --from 16, then rebuild and ship
Touches your metadata? it never rewrites your metadata — but it can start refusing it (measured) yes — you edit your source, guided by the tool's change list

Most upgrade questions are really the question which of these am I doing. You can do either one alone. A platform move does not rewrite your app, and republishing your app does not move the runtime.

**The short version.** Moving the runtime forward one major keeps working with metadata authored against the previous major — the loader converts it as it reads. Falling **two** majors behind is what breaks, because the conversion window is one major wide. See [when a platform move forces an app move](#when-a-platform-move-forces-an-app-move). **A minor is not automatically a no-op.** The paragraph above is about *metadata compatibility* across a major boundary, and that is the only thing the major number promises. It does not promise that moving between two releases **inside** one major changes nothing. v17's own minors have narrowed what the write path accepts, flipped a self-registration default to the safe end, renamed a published SDK namespace with no aliases, and started enforcing constraints that were declared but inert — none of which the protocol handshake or the metadata conversion window has anything to say about. Read the checklist for **every release you cross**, not only for every major: [the table below](#per-release-specifics) lists them.

The platform runtime

The platform ships as a single version-locked train: every @objectstack/* package shares one version number, and that number is the platform version.

Moving the tag

The official image is ghcr.io/objectstack-ai/objectstack, and its tags mirror @objectstack/cli versions: the exact X.Y.Z, plus the rolling X.Y, X and latest tags. Pin the exact version in production and move it deliberately:

# docker-compose.yml, or your orchestrator's manifest
image: ghcr.io/objectstack-ai/objectstack:17.3.0

On a host running the artifact directly under systemd, the same move is a file swap: replace the artifact and restart the service. Roll back by restoring the previous artifact.

See Self-hosting for both deployment shapes in full.

Moving the dependency pins

Not every deployment moves a tag. An app that consumes the platform as npm dependencies — @objectstack/* in its own package.json, which is the shape create-objectstack scaffolds — carries the platform version in its dependency tree and moves it there. There is no os command for this move; it is three steps you run yourself.

  1. Bump every @objectstack/* dependency together, to the same version. The train is version-locked — every package on it shares one version number — so a partial bump produces a combination that was never built or released as a set. Include devDependencies: @objectstack/cli is the os binary that validates and builds your app, and a CLI left a release behind runs the previous release's author-time rules over your metadata.
  2. Regenerate the lockfile, and commit it (pnpm install / npm install / yarn install). This is the step that actually moves the code. A project pinned to exact versions moves because step 1 edited the pins; a project on the scaffold's default ranges (^17.0.0) moves entirely here. Read whatever peer-dependency warnings this prints — the --frozen-lockfile install your CI runs skips resolution and will never print them.
  3. Check the two protocol declarations your app ships — specVersion in objectstack.manifest.json, and engines.protocol in your defineStack manifest. Both name the protocol major, so a move inside one major leaves both alone, and a major boundary is where they change. Move them deliberately when you cross one; never edit them to silence a mismatch.

Then run the loop below — os validate before os build — because moving the pins can move the gate.

What the boot does when the database disagrees

Moving the runtime can leave the physical database shaped for the previous version. What happens next depends on which deployment shape you run.

The standing production policy is hands-off. Under NODE_ENV=production, automatic reconciliation is ignored and every divergence is warned about, on the assumption that an operator runs os migrate deliberately:

os migrate plan     # how the database has drifted, categorised safe / needs-confirm / destructive
os migrate apply    # applies the loosening changes
os migrate apply --allow-destructive   # the narrowing ones, once you have read the plan

The artifact-pinned boot is stricter, because there is nobody at a terminal: a container simply comes up carrying a different artifact than the one that shaped the database. On that path the boot applies safe and needs-confirm drift itself, and refuses to start on destructive drift, printing every change and the command that resolves it. Nothing is skipped silently — "shrug and serve" is the state that gate exists to delete. The refusal happens before the HTTP port binds, so a refused boot is a boot that never served traffic.

A runtime move can still force metadata edits

The table at the top of this page says a runtime move does not touch your metadata. That is true in the narrow sense — nothing rewrites your source files — and it is not the same claim as no metadata work is needed. The difference has been measured.

An application repository was upgraded across a single minor, 17.2.0 → 17.3.0, by a reader holding only this documentation, the CHANGELOG.md files inside the published npm tarballs, and the os CLI's own output. Moving the pins and restarting was not enough:

  • os validate refused the stack, and so did os build. The release registered one more author-time rule — the count printed by os validate moved from 41 to 42 — and two objects that compiled on 17.2.0 stopped compiling. That is a build-stopping gate, not a warning.
  • A lint family widened onto surfaces it had not read before. In that app the count went from zero findings to 429.
  • A constraint that had been declared but inert started being enforced, so nine identifier fields acquired a unique index on the next migration.

None of that is a protocol-major event. It does not appear in the conversion window described below, and os migrate meta has nothing to replay for any of it — see "Nothing to migrate" is not "you are done". The only channel that carries these is the release's own checklist, under Per-release specifics.

**After any runtime move, minor included, run `os validate` before you ship.** A stack that built clean on the release you are leaving is not evidence that it builds clean on the one you are landing on.

When a platform move forces an app move

Each package declares the protocol major it was authored against, and the runtime checks that handshake first, before it loads anything:

manifest: {
  // ...
  engines: { protocol: '^17' },
}

The load path then converts old metadata shapes to the canonical current shape as it reads them, emitting a deprecation notice per conversion. That window is exactly one major wide. Metadata authored against the previous major loads and runs; a shape retired one major further back is rejected, and the rejection carries the fix — the old spelling, the new spelling, and the command that lists every site to edit.

The practical consequence:

  • One major behind — it runs. You will see conversion notices in the boot log. Migrate at your convenience.
  • Two or more majors behind — the load rejects the retired shapes. The metadata half is no longer optional, and it is the next section.

The metadata app

Your app is versioned by you, upgraded by you, and shipped as a compiled artifact. Upgrading it across one or more protocol majors is one command followed by your normal build.

One command covers every major you skipped

os migrate meta --from 15     # the major your metadata was authored against

--from is the major you wrote against, not the one you are going to. The command replays every step between that major and this runtime's, in order, in a single pass — so upgrading across skipped majors does not mean running it once per major, and does not mean reading several release checklists and merging them by hand:

You ran Steps it replays
os migrate meta --from 16 17
os migrate meta --from 15 16, 17
os migrate meta --from 14 15, 16, 17
os migrate meta --from 12 13, 14, 15, 16, 17

The chain reaches back to protocol 10 — that floor is a release-policy decision, not an accident of what still exists. Below it the command refuses with a message naming the floor rather than half-migrating you.

Useful flags:

Flag What it does
--step Report each major's hop separately, so a failure bisects to the exact major
--out migrated.stack.json Also write the migrated stack as a JSON snapshot — the only file the command writes
--to 16 Stop at an intermediate major instead of this runtime's
--json Machine-readable output, for CI or an agent

It reads your source and no database. (Its sibling, os migrate meta --stored, does the opposite — it rewrites one deployment's stored metadata rows and reads no config. The two are mutually exclusive.)

What it does not do — read the output

**`os migrate meta` does not rewrite your source files.** It replays the chain over the loaded stack *in memory* and reports the diff; the only file it writes is `--out`, a JSON snapshot. Porting the listed edits into your own `.ts` sources is your work — use `--out` as the oracle you diff against, never as the file you ship. It also applies the **mechanical** changes only, and never guesses at the rest. Changes that cannot be converted losslessly are reported as structured to-dos for you to resolve — and a clean-looking run can still carry dozens of them. The command's output is the work list, not a receipt. **"Nothing to migrate" is not "you are done".** This command's scope is the protocol chain, so on a move **inside** one major it has — correctly — nothing to replay, and says so: 
$ os migrate meta --from 17
Nothing to migrate — the metadata is already canonical for this range.

That sentence is true, and it is narrow. It is silent about author-time rules added inside the major, lint families that widened, defaults that flipped, declared constraints that started being enforced, and grants that changed meaning — none of which is a protocol conversion, and any of which can stop your build or change your runtime's behaviour. Measured on one 17.2.0 → 17.3.0 upgrade: the command printed exactly the line above and exited 0 while nine separate changes were live and unaddressed on that stack. Read it as the protocol chain is clean, then get the rest from Per-release specifics.

That split is the reason the per-major checklists below still matter: renames and retired keys the tool enumerates for you; decisions it cannot make for you stay yours. The run also ends by naming the per-deployment data migrations that remain (os migrate files-to-references, os migrate value-shapes, and friends) — scoped to the field classes your metadata actually declares. It reads no database, so that list is what is left to consider, never what this deployment has already done.

The loop

os migrate meta --from 15     # 1. read the mechanical change list and the to-dos
                              # 2. apply the edits by hand; resolve the to-dos
                              #    and the checklist items below
os validate                   # 3. the gate — schema, CEL predicates, widget bindings
os build                      # 4. compile to dist/objectstack.json
                              # 5. ship the artifact; restart
os migrate plan               # 6. reconcile the database to the new metadata

Step 3 is the real gate: os validate runs the same checks as os build but writes no artifact, which makes it the fast inner loop while you work through the to-dos. Full command reference in the CLI documentation.

Per-release specifics

Everything above is the mechanism. The contents of a given release — which keys were renamed, which defaults changed, which grant you now have to declare explicitly — live on that major's release page, written for app authors and compiled at release time.

Read the checklist for every release you are crossing, not only the one you are landing on — and that means every minor inside a major as well as every major boundary. A minor moves the runtime without moving your metadata's protocol major, so os migrate meta has nothing to replay for it; that is exactly why the minor's own accept-set tightenings, default flips and authorization narrowings have no other channel to reach you than the page below.

Release Where its upgrade notes live
v17.3.0 Upgrade checklist — 17.3.0
v17.2.0 Upgrade checklist — 17.2.0
v17.1.0 Upgrade checklist — 17.1.0
v17.0.0 Upgrade checklist — 17.0.0
v16.0.0 Upgrade checklist
v15.0.0 Upgrade checklist
v14.0.0 Upgrade checklist
v13.0.0 Upgrade checklist
v12.0.0 Upgrade checklist
v9.0.0 Upgrade checklist

Only the v17 line is broken out per release. Each of its three minors shipped breaking changes under the repo's launch-window convention — which ships a breaking change as minor rather than major, so the version number is not the migration signal and the changelog entry is. Earlier majors' release pages carry one checklist per major, which is what those rows link to.

The release notes overview summarizes what each major changed.

The per-package changelogs are the exhaustive record

The release pages above are triaged, deliberately: a change is written up there when it can be reached from something an application ships or operates, and changes that move only the platform's own internals are left out. That triage is what makes a release page readable — 17.3.0 alone carries 862 changelog entries across the train — and it is also the page's limit.

The exhaustive record is the CHANGELOG.md shipped inside every published package, so you already have a copy of the ones that matter to you:

less node_modules/@objectstack/spec/CHANGELOG.md
less node_modules/@objectstack/cli/CHANGELOG.md
# …one per @objectstack/* package your app depends on

Read them whenever a release checklist does not explain what you are seeing, whenever you maintain a plugin or a driver against our internal contracts, and whenever you are crossing several releases at once. They are per-change, and they carry the reasoning and the migration for entries too narrow to reach a release page. On one measured documentation-only upgrade, these files — not the release pages — were where the answer to every question turned out to be, which is why this section is here rather than one line about two old majors. Curated notes for v10 and v11 were never backfilled at all, so for those two majors the changelogs are the only record there is.

What a major is allowed to change in the first place — which edits count as breaking, and the deprecation window a property must sit through before it can be removed — is the Backward Compatibility Policy.

Not this page

Upgrading an installed package — a template app or a third-party package already installed into a deployment — is a different operation with its own lifecycle (pre-check, plan, snapshot, execute, validate, commit or roll back). It is neither of the two halves above: it moves someone else's metadata inside your deployment. See the package upgrade protocol.