Upgrades and rollback
V2 has no auto-updater, database migration runner or universal rollback command. An engine update is an operator-managed change to a selected revision and its dependencies/assets. Keep it separate from ordinary source edits and from public hosting settings. The official showcase remains pinned; this page explains maintenance of your own installation.
Decide what is changing
| Change | Scope |
|---|---|
| Prose, media | Saved content, static bytes and rebuild |
| Branding, links | Effective config, runtime and next output |
| Engine | Builder, editor, modules, template, static implementation |
| Dependency | Package, lockfile, bundle, license compatibility |
| Host, service | Node, process, proxy, cache, domain behavior |
| Data restore | Account, history, source state and writer coordination |
Calling all of these “update” hides rollback risk. Name the intended layer and success criteria. A new engine checkout should not blindly overwrite custom content or private runtime. A content-only release should not regenerate libraries or change authentication.
Baseline before staging
Record current engine commit, Node/version, dirty/tracked/untracked source, configuration, templates/assets, runtime selection, live output/host and latest publisher state. Confirm no publication is running. Preserve a verified backup and known reader artifact before altering anything.
| Evidence | Why |
|---|---|
| Source diff | Uncommitted work is not protected by commit ID |
| Runtime paths | Prevent accidental empty, new account database |
| Lockfile, assets | Keep dependency, browser versions coherent |
| Route map | Detect renamed, normalized paths |
| Host, service settings | Reproduce executable, bind, cookie, proxy behavior |
| Last known artifact | Restore reader without rebuilding uncertain code |
Do not run pull/reset/clean over dirty production hoping it preserves everything. Git does not include ignored private runtime or every external media file. Backups containing hashes/accounts/history remain private. Backup and restore explains consistency and rehearsal.
Stage selected engine
Use a new separate checkout. Inspect its selected release/source diff and Node requirement; install its lockfile, run its tests and record actual outcomes. Tests exercise that revision’s fixtures, not your whole site/host. Do not carry forward the old test count as a requirement for a changed release.
Copy site inputs deliberately. Preserve new implementation files. Reapply reviewed template/style changes as a diff rather than copying the old entire engine tree. Identify obsolete files that could become public if left in static output.
| Input | Staging decision |
|---|---|
| Content, config | Copy selected reviewed site source |
| Media, downloads | Copy intended public files, check provenance |
| Templates, CSS | Port reviewed customization to new contracts |
| Links, settings, icons | Point at protected rehearsal copies |
| Users, history | Restore protected rehearsal snapshot if editor tested |
| Sessions | Not portable; fresh login |
| Publish marker | Metadata indicator, not compatibility proof |
Point staged editor at separate protected rehearsal accounts/runtime, not the production users file, unless an explicitly coordinated cutover is underway. Simply using a different port does not isolate file writes. Sharing live runtime during tests can reset accounts, change grants or create mixed history.
Compatibility review
| Area | Compare |
|---|---|
| Routes | Titles, normalization, collisions and incoming links |
| Frontmatter, rendering | Supported fields, raw HTML and Markdown extensions |
| Reader | Search, anchors, themes, media, copy and mobile |
| Runtime | Validated keys, account model and file compatibility |
| Perimeter | Hosts, proxies, cookies, CSRF and limits |
| Publisher | Snapshot, verify, swap, rollback, error behavior |
| Assets | Versions, globals, loaders, notices and browser target |
The manifest is evidence for asset bytes/versions, not automatically verified signatures. Bundle regeneration is a maintainer-only destructive vendor operation. Review selected package/lockfile/bundle together; see Local assets.
Build isolated output with explicit data/content/output selection. Review every changed route and old-link handling. Test intended staging host at actual root/subpath and fresh/existing browser caches. A browser preview of old default dist does not validate an arbitrary new --out.
Cutover plan
- Name artifact, code and data being switched, with exact operator-controlled paths.
- Confirm backup/return path and compatibility; rehearse before the window.
- Coordinate writers and wait for any publication to finish.
- Switch reader output through the supported host process.
- If the editor changes, switch selected engine/service/runtime coherently and restart deliberately.
- Verify live reader plus private editor/auth/permissions as applicable.
- Record actual outcome and any gaps before resuming normal writes.
A direct build removes its output after preflight. A staged static-host switch can reduce exposure, but exact availability/cache behavior belongs to your host. The editor publisher uses two renames, not guaranteed atomic serving. A post-switch marker/backup warning can coexist with live new output; inspect state before retrying.
Restart loses sessions, current job state/log and limiter maps. It does not undo saved accounts/source/history. Tell operators to sign in again; do not misdiagnose expected session loss as account corruption.
Rollback by failed layer
| Failure | Return path |
|---|---|
| Wrong reader artifact | Restore prior reviewed output; check host, cache |
| Engine regression | Prior compatible engine, config, assets and dependencies |
| Bad content, routes | Reviewed prior source, artifact with link policy |
| Runtime corruption | Coordinated compatible protected snapshot |
| Host configuration | Supported host, service rollback and live verification |
Preserve failed output/logs for diagnosis without exposing private bytes. Do not roll back only accounts while newer writers/sessions remain live, or overlay old runtime onto a new incompatible format. Review password/grant/auth-version effects, not just whether login succeeds.
dist.previous is one operational reader backup, not a full rollback product. It may be absent on first publish, rotated away or retained under a reported .old-<id> name after failure. Follow actual paths and verify bytes. Reverting a hosting commit does not restore private account/source state automatically.
Close the maintenance window
Inspect current distinctive prose, deep routes, resources/search, real 404, diagram and both themes. For an editor, verify protected bind/hosts/cookies, synthetic role/grants, save/publish/history and selected private paths. Confirm removed files are not public and cached old assets do not mask the result.
Record tested revision, actual gates, deployment/return artifact and anything not exercised. No production service cutover/private-runtime rollback is claimed by this page. Update checklist is a concrete preparation flow; Review and release supplies acceptance gates.