Design updates and rollback

Shipping 1.0 is the start of a loop. Users need a way to learn about new versions, get them safely, and — when an update goes wrong — get back to a version that works.

Match the mechanism to your distribution path. A source-first project can announce releases on the repository and keep tagged versions buildable. A direct-download app can document a manual flow (a “Check for Updates” menu item that opens the releases page), or integrate an update framework.

The Sparkle-style model is the standard for direct distribution: the app periodically fetches an appcast feed listing versions and download URLs, and every update is cryptographically signed with a key only you hold. The app verifies the signature before installing. Two properties are non-negotiable whatever tool you use: the update channel is HTTPS, and the update verifies origin and integrity before replacing anything. An unsigned update channel is a remote code execution service with your app’s name on it.

Whatever the mechanism, every published update gets the same treatment as a first install — notarized, stapled, and checksummed:

shasum -a 256 Notes-1.3.0.zip

Updates ship with data. If version 1.3.0 migrates the notes database, make a backup first and record a format version inside the data store. My rule: decide the supported rollback window, then keep every version in that window able to read the current format — or keep the pre-migration backup restorable.

Test the ugly paths, because updates fail in the field constantly: a download interrupted halfway, no network, a disk nearly full, and a user jumping from 1.0.2 straight to 1.4.0 past three migrations.

Write the rollback plan down before you need it: which previous artifact stays downloadable, whether it can read data written by the current version, and the exact steps to restore a migration backup.

The failure that teaches this lesson: 1.3.0 migrates the database, a crash appears, and users reinstall 1.2.0 — which opens the migrated file and silently corrupts it. The old binary alone is not a rollback plan. The old binary plus compatible data is.