Score an upgrade before the maintenance window

Verifiedon 2026-08-022026.7.1

Release review is a boundary exercise

An upgrade is not “new code installed.” It is a coordinated change to a running system whose code, configuration, databases, credentials, plugins, service supervisor, integrations, and recovery path may have different compatibility rules. Release notes are a starting source, not an approval. The operator’s job is to translate each change into a question: which boundary could move, what evidence would show the move is safe, and what is the smallest environment in which we can learn that answer?

Use the exact target version and source revision in the record. This course uses stable 2026.7.1 and upstream revision 2d2ddc43d0dcf71f31283d780f9fe9ff4cc04fe4 as its verified scope. The v2026.7.1 release page is the product-facing primary receipt; the GitHub release tag is the immutable release identity. The live docs were checked 2026-08-01 UTC. If the current target is newer, fork the record and re-review rather than silently stretching the old receipt.

The isolated recovery game-day receipt is supporting evidence, not a release-wide approval. Its tarball integrity matched the registry and the real CLI reported OpenClaw 2026.7.1 (2d2ddc4), but the restore-command limitation remains open.

1. High impact with unknown evidence is a defer or seek-review state.
2. A sandbox decision is appropriate when the next check can be isolated and observed.
3. Verified evidence still needs a named owner and acceptance check.
4. Every point in the score should have a statement of what would lower it.

Read release notes for operational consequences

Mark every release-note line that can affect one of these surfaces:

• Configuration: renamed, removed, defaulted, or newly required keys; parser or schema changes.
• State: migrations, SQLite schema versions, transcript/session storage, queue semantics, or data repair.
• Service lifecycle: startup, readiness, restart handoff, crash-loop behavior, runtime or Node requirements.
• Integrations: channel APIs, plugin compatibility, authentication, external provider behavior, or webhook contracts.
• Permissions and exposure: new routes, control-plane methods, scopes, browser/tool policy, or network defaults.
• Rollback: downgrade support, one-way migration, package-manager behavior, or a need for a pre-change state restore.

The current Update reference says openclaw update --dry-run previews planned actions without writing config, installing, syncing plugins, or restarting. It also documents --json, --no-restart, channel selection, and the fact that downgrades can break configuration. The Updating guide distinguishes package installs from source checkouts and warns that manual package replacement should stop a managed gateway first. Those are operational constraints, not optional prose.

The Database schemas reference adds a critical rollback test: older builds refuse databases written by a newer schema. A binary downgrade does not downgrade data. Therefore, a review that says “we can npm install the previous version” without a pre-change backup and schema check has not described a viable rollback.

Use an explicit scorecard

Assign one point for each unresolved factor:

1. configuration or default migration is not understood;
2. state schema or data migration is possible;
3. an external integration or plugin changes;
4. a permission, network, or exposure boundary changes;
5. rollback compatibility is unclear or one-way migration is possible;
6. backup verification or restore proof is missing;
7. no representative sandbox exists;
8. a critical acceptance check has no named owner;
9. the maintenance window cannot contain the expected restart or drain;
10. the target, install root, or revision is ambiguous.

Interpret the total as a prompt for evidence, not a universal risk law:

A low score cannot override a hard stop. An unverified database restore or an unknown production credential is a defer state even if every other row looks routine.

Worked example: a release with unclear compatibility

Imagine a synthetic release note says “improves channel startup and updates session storage,” while the migration page does not state whether the old build can read the new database. The review record should not claim that the change is safe. It should say:

Target: v2026.7.1 / stable / revision cc570a74532e…
Affected: channel startup, per-agent session state, gateway restart behavior
Unresolved points: session schema direction; plugin probe coverage; restore time
Score: 6 (state, integration, rollback, backup proof, sandbox, acceptance owner)
Decision: seek technical review, then sandbox; not production
Evidence to lower score: current schema reference, verified restore, plugin post-upgrade check,
  representative channel probe, named acceptance owner
Stop trigger: any newer-schema error, missing restore, or channel regression

The decision is useful because it names what “ready” means. “Looks risky” is a mood. “Six unresolved factors; no production action; resolve these five evidence items” is an operational control.

openclaw update status --json && openclaw update --dry-run --json

Run those commands only in the approved environment and compare the result with the exact docs for the installed version. --dry-run is preview evidence, not a backup and not a rollback rehearsal. Record the install root and service owner separately; a shell command can point at a different installation than the managed service.

Lab: produce a one-page release review

Choose a real release page only if your environment permits source review, or use a synthetic release note. Do not invent product changes. Complete these steps:

1. Capture the exact source URL, tag/version, upstream revision if available, and review timestamp.
2. Highlight every statement with a possible configuration, state, service, integration, permission, or rollback consequence.
3. Map each consequence to an affected boundary and one acceptance check.
4. Score the ten unresolved factors. For every point, write the evidence that would remove it.
5. Choose go to sandbox, defer, or seek technical review. Do not write “go to production from release notes alone.”
6. Name the maintenance owner, reviewer, window, stakeholder notification, rollback trigger, and evidence location.

Expected output is a one-page change record that another operator can use to schedule the next safe step. Failure cases include relying on a version label without a revision, counting a dry run as backup proof, or treating a vague migration note as compatible. Roll back the exercise by marking the decision pending and retaining the source receipt; do not downgrade or install anything to make the worksheet look complete. The learner artifact is the scored review plus a short “evidence that would change my decision” section.

Checkpoint: vague backwards compatibility

A migration note says nothing about whether the previous build can read the new state. Count unclear rollback as an unresolved factor and seek review or defer. Do not “test the downgrade quickly” against the only state copy. Create a verified pre-change recovery point first, then use a fresh isolated target if the review owner approves the experiment.

Publication boundary

This lesson teaches the review method and uses current official references; it does not authorize a production upgrade. The course is published for the verified 2026.7.1 scope after independent technical review reconciled the release-specific instruction, receipt digest, dependency index, and supported-version range. Primary receipts: Update CLI, Updating, Database schemas, v2026.7.1 release notes, and the immutable GitHub tag.