Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,090 of 9,090 pages
About the help in other languages
All help pages

Upgrades without surprises

How a business plans, rehearses and runs an Exponential upgrade so that customers notice nothing but the improvements, with the phases, the roles, the tools that ship with the product and the decisions to make before…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/businesses/reliability/upgrades-without-surprises.md

On this page

Upgrades without surprises

This page is for owners and managers who approve upgrades, and for the project lead who plans them. It explains why regular upgrades are a reliability measure, how an upgrade is planned and rehearsed, which tools ship with Exponential to make it predictable, and what to decide before the window opens. The detailed plan, with a copyable checklist, is Release and upgrade planning; the technical steps are in Upgrading.

Contents

  1. Why upgrading is a reliability measure
  2. How often
  3. The phases of an upgrade
  4. The tools that make it predictable
  5. Two ways to update: command line or administration
  6. Decide before the window
  7. The one rule
  8. Checklist for the business

Why upgrading is a reliability measure

Security fixes reach you only through the next 6.0.x release: "A published tag is never changed: a fix for a problem in v6.0.14 or an earlier tag reaches you as the next release, not as a corrected copy of the old one" (SECURITY.md). A site that does not upgrade slowly collects known problems, and its next upgrade grows larger and riskier.

Small, regular upgrades are the opposite: each one is short, well understood and easy to rehearse. The planning page says it as a rule: "Treat 'upgrade to the newest 6.0.x' as a recurring task, not a one-off project" (Release and upgrade planning).

How often

From Release and upgrade planning, deciding when to upgrade:

SituationRecommendation
A security release exists for your lineUpgrade in the next possible window
You run 6.0.x and are one or two releases behindPlan a routine upgrade
You run 6.0.7 or older on PHP 7.4Move to 6.0.15 on PHP 7.4 (usable without support), then plan the PHP move; 6.0.8 to 6.0.14 need PHP 8.1
You run 5.x or olderPlan a project (Upgrading)
You have your own changes in kernel filesPlan time for merging them

Live sites should follow release tags; the development line main "moves every day; a tag never changes" (same page). See Release line and support policy.

The phases of an upgrade

The planning page lists eleven phases; in business terms they group into four (Release and upgrade planning, phase by phase):

GroupPhasesWhat the business sees
PrepareInventory, read the release notes, estimate, run the upgrade checkA list of things to check, with owners and an estimate
ProveRehearse on a copy, editors accept the copyA signed-off rehearsal and a measured duration
DoAnnounce, back up, upgrade inside a maintenance windowA short window at a quiet time
ConfirmVerify, run the upgrade check again, record the new versionsA short report: what changed, what was checked

The rehearsal is what removes surprises. "Your own window depends on your site; the rehearsal in phase 5 tells you how long it really takes. Write that measured time into the plan, not a guess" (same page).

The tools that make it predictable

ToolWhat it does for the businessRead
Changelogs and behavior change notesSay what changed and what to check, per release and periodRelease line and support policy
Setup > System informationRecords the versions before and after; warns about PHP and settingsSystem information
Setup > Upgrade checkCompares files and database with the release, only readingUpgrade check and file consistency
Maintenance modeA clean 503 page while the work happensMaintenance mode and planned work
exp:velocity deployRuns the code reload and cache steps in the right order, stops at the first failureGraceful deploys
The audit trailRecords the maintenance window, deploys and settings changesAudit trail for operations
ezupdateChecks for updates and runs Composer from the administration, with a dry runAutomated updates with ezupdate

Two ways to update: command line or administration

A site made of Git clones can be updated on the command line or from the administration (Update with Git):

Command lineAdministration
ForAdministrators with a shell on the serverAdministrators without a shell
Kernelgit merge of the newest release tag, or another branchGit Manager pulls a branch; it cannot merge a release tag
Extensionscomposer updateUpdates and packages runs Composer in the background, with Preview first; off until [UpdateSettings] AllowUpdate is switched on
Code reloadexp:velocity deploy on a Velocity siteCache management; it cannot restart Velocity

The page's summary: the command line "can do everything", while the administration "covers a routine update of a site that follows a branch ... without opening a shell, but a release tag, a merge conflict and the Velocity restart still need the command line".

About automation: ezupdate "has no schedule of its own that updates a site unattended, and the shipped switches keep updating and installing off until an administrator turns them on" (Automated updates with ezupdate). The update-with-Git page describes a self-updating script for sites that choose it (Let it update itself); for a live business site, a rehearsed upgrade in a window is the safer default.

Decide before the window

  • Go or no-go: who decides, and by when, that the window goes ahead.
  • Rollback: who decides to roll back, and by when. "A rollback is 'restore the backup' for the database and 'check out the previous tag' for the code; it is only possible if the backup was tested" (Release and upgrade planning, when something goes wrong).
  • Communication: who tells customers the site is back, or that the window is extended.
  • Editing freeze: editors stop publishing during the window and know when they may start again.
  • On call: who is reachable for the first day after the upgrade.

The one rule

"Never run an installer over an existing site. The setup wizard, the kickstarter and exp:install create a new database. An upgrade replaces the code and updates the existing database in place" (Release and upgrade planning, the one rule). Put this rule into the briefing of everyone who touches the server.

Checklist for the business

  • To do: Upgrading to the newest 6.0.x is a recurring item in the calendar.
  • To do: Each upgrade has an owner, a rehearsal on a copy and a measured duration.
  • To do: Editors accepted the rehearsed copy.
  • To do: The window is at a quiet time, announced, and covered by a fresh, tested backup.
  • To do: Go/no-go and rollback decisions have named owners.
  • To do: The upgrade check was run before and after, and the reports are kept.
  • To do: The new versions are recorded in the handover document.

The full technical checklist to copy into a ticket is on Release and upgrade planning, upgrade checklist.

Become an Exponential Partner

Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x